@engenty/wizards-runtime 0.0.0-stage → 0.7.5

package/apps/runtime/dist/debug.js

@@ -0,0 +1,196 @@
+import { arch, hostname, platform } from "node:os";
+import { desc, eq } from "drizzle-orm";
+import { accountToken, linkedAccount } from "./auth/account.js";
+import { packageVersion } from "./cli/home.js";
+import { db, knownTenants, schema, withTenant } from "./db/client.js";
+import { env } from "./env.js";
+import { logState, startedAt, tail } from "./log.js";
+import { managed } from "./manage.js";
+import { modelSettings } from "./models.js";
+import { loadedPlugins } from "./plugins/registry.js";
+import { runIndexOf, tenantOfRun } from "./tenants/control.js";
+import { LOCAL_TENANT } from "./tenants/tenant.js";
+/**
+ * What an installation tells about itself when someone looks at it from afar
+ * (docs/plans/remote-debug.md): its status, the lines it printed, one run, a tenant's models.
+ * Nothing here holds a key or a person's answers; the log ring took the secrets out already.
+ * The Manage-App asks a runtime of its own over `/api/internal/debug/*`; a runtime that runs
+ * alone answers the command line over `/api/local/debug/*` and sends a report to its account.
+ */
+/** This process, as every installation names itself. */
+export function processStatus() {
+    const memory = process.memoryUsage();
+    return {
+        pid: process.pid,
+        node: process.version,
+        platform: `${platform()} ${arch()}`,
+        hostname: hostname(),
+        startedAt: new Date(startedAt).toISOString(),
+        uptimeSeconds: Math.round((Date.now() - startedAt) / 1000),
+        memoryMb: Math.round(memory.rss / 1_048_576),
+        log: logState(),
+    };
+}
+export async function status() {
+    const tenants = await knownTenants().catch(() => []);
+    return {
+        app: "engenty-wizards-runtime",
+        version: packageVersion(),
+        process: processStatus(),
+        managed,
+        appUrl: env.appUrl,
+        manageUrl: env.manage.url || null,
+        gatewayUrl: (managed ? env.manage.gatewayUrl : env.local.gatewayUrl) || null,
+        sandbox: env.sandbox,
+        browser: env.browserCdpUrl ? "cdp" : "local",
+        files: env.s3.bucket ? "s3" : "data folder",
+        database: env.databaseUrl ? "libsql" : "file",
+        tenantDatabases: env.tenantDbUrlTemplate ? "libsql" : "files",
+        tenants: tenants.length,
+        plugins: loadedPlugins().map((p) => ({
+            id: p.source.id,
+            version: p.source.manifest.version ?? null,
+        })),
+    };
+}
+const from = () => hostname();
+/** The lines this process printed. */
+export function logs(query) {
+    const own = from();
+    return {
+        sources: [{ from: own, ok: true }],
+        lines: tail(query).map((line) => ({ ...line, from: own })),
+    };
+}
+/** One run, whichever tenant it belongs to: its state, its error, what the line knows, its last events. */
+export async function runDetail(runId) {
+    if (!/^[A-Za-z0-9_-]{1,64}$/.test(runId)) {
+        return null;
+    }
+    const tenantId = await tenantOfRun(runId);
+    if (!tenantId) {
+        return null;
+    }
+    return withTenant(tenantId, async () => {
+        const run = await db.query.run.findFirst({
+            where: eq(schema.run.id, runId),
+            columns: {
+                id: true,
+                wizardId: true,
+                version: true,
+                mode: true,
+                status: true,
+                cursor: true,
+                error: true,
+                ask: true,
+                unattended: true,
+                costMicros: true,
+                userId: true,
+                createdAt: true,
+                updatedAt: true,
+                expiresAt: true,
+            },
+        });
+        if (!run) {
+            return null;
+        }
+        const [wizard, events, line] = await Promise.all([
+            db.query.wizard.findFirst({
+                where: eq(schema.wizard.id, run.wizardId),
+                columns: { title: true, publishedVersion: true },
+            }),
+            db
+                .select({
+                id: schema.runEvent.id,
+                stepId: schema.runEvent.stepId,
+                type: schema.runEvent.type,
+                message: schema.runEvent.message,
+                createdAt: schema.runEvent.createdAt,
+            })
+                .from(schema.runEvent)
+                .where(eq(schema.runEvent.runId, runId))
+                .orderBy(desc(schema.runEvent.id))
+                .limit(60),
+            runIndexOf(runId),
+        ]);
+        return {
+            tenantId,
+            run: {
+                ...run,
+                ask: run.ask ? { id: run.ask.id, kind: run.ask.kind } : null,
+                costCredits: Math.round(run.costMicros / 10_000) / 100,
+            },
+            wizard: wizard ? { id: run.wizardId, ...wizard } : null,
+            line,
+            events: events.reverse(),
+        };
+    });
+}
+/** Where each class of a tenant runs, as its settings page shows it; never a key. */
+export async function tenantModels(tenantId) {
+    if (!/^[A-Za-z0-9_-]{1,64}$/.test(tenantId)) {
+        return null;
+    }
+    const known = await knownTenants();
+    if (!known.includes(tenantId)) {
+        return null;
+    }
+    return withTenant(tenantId, async () => {
+        const settings = await modelSettings();
+        return {
+            tenantId,
+            source: settings.source,
+            bindings: settings.bindings,
+            creditFallback: settings.creditFallback,
+            keys: settings.keys,
+            ways: settings.ways,
+        };
+    });
+}
+export class ReportError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/**
+ * A runtime that runs alone sends its account what a look from afar needs: its status, its
+ * model settings (never a key) and the last lines it printed. The person asks for it
+ * (`wizards report`); nothing goes by itself.
+ */
+export async function sendReport() {
+    const account = await linkedAccount();
+    const token = account ? await accountToken() : null;
+    if (!account || !token) {
+        throw new ReportError("no_account", "This install is linked to no account.");
+    }
+    const [state, models] = await Promise.all([status(), withTenant(LOCAL_TENANT, modelSettings)]);
+    const body = {
+        kind: "install",
+        version: state.version,
+        status: state,
+        models: {
+            source: models.source,
+            bindings: models.bindings,
+            creditFallback: models.creditFallback,
+            keys: models.keys,
+            ways: models.ways,
+        },
+        logs: tail({ limit: 500 }),
+    };
+    const res = await fetch(`${env.local.accountUrl}/v1/diagnostics`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(20_000),
+    }).catch((err) => {
+        throw new ReportError("not_sent", `The account did not answer: ${err.message}`);
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new ReportError("not_sent", `The account answered ${res.status}: ${text.slice(0, 200)}`);
+    }
+    const { id } = (await res.json());
+    return { id, to: env.local.accountUrl };
+}

package/apps/runtime/dist/docs/dev/index.md

@@ -0,0 +1,41 @@
+---
+title: Developer
+description: Extend engenty wizards with plugins – tools for AI steps, routes with their own tables, pages in the studio.
+version: 0.5.0
+---
+
+You extend engenty wizards with **plugins**. A plugin adds to a runtime without changing its
+code, and the runtime loads it from its files while it runs.
+
+## Start here
+
+| | |
+|---|---|
+| [What a plugin is](./plugins/index.md) | The two halves, what each can add and what a plugin may touch |
+| [Quick start](./plugins/quick-start.md) | A tool for AI steps in one file that works in two minutes |
+| [Reference](./plugins/reference.md) | Every call, type, address and setting |
+| [Examples](./plugins/examples.md) | Two plugins to read and copy |
+
+## Wizards as files
+
+A wizard is JSON, and it travels as a `.wizard` file. [The wizard format](./wizard-format.md)
+describes the format, the JSON Schema for your editor and `wizards validate`.
+
+## What you need
+
+- engenty wizards on your computer, or a checkout of
+  [engenty/wizards](https://github.com/engenty/wizards).
+- TypeScript. The runtime reads a plugin’s server half as TypeScript, without a build.
+- A checkout, if your plugin draws in the studio: you build its studio half with the studio’s
+  own tools.
+
+## Working on engenty wizards itself
+
+These pages are about extending engenty wizards. The documents about its own code are in the
+repository:
+
+| | |
+|---|---|
+| [docs/development.md](https://github.com/engenty/wizards/blob/main/docs/development.md) | How to run it from source, the checks, how it is built and how it is released |
+| [docs/marketplace-contract.md](https://github.com/engenty/wizards/blob/main/docs/marketplace-contract.md) | What a runtime and the marketplace say to each other |
+| [docs/copy-style.md](https://github.com/engenty/wizards/blob/main/docs/copy-style.md) | How the app talks to people: the voice, the glossary and the rules for every string |

package/apps/runtime/dist/docs/dev/meta.json

@@ -0,0 +1,7 @@
+{
+  "title": "Developer",
+  "description": "Extend engenty wizards with plugins: tools for AI steps, routes with their own tables, pages in the studio.",
+  "root": true,
+  "icon": "SquareTerminal",
+  "pages": ["index", "wizard-format", "plugins"]
+}

package/apps/runtime/dist/docs/dev/plugins/connections.md

@@ -0,0 +1,74 @@
+---
+title: Accounts
+description: Accounts a plugin connects for a space, such as a calendar or a mailbox, through the runtime's built-in connectors.
+version: 0.5.0
+---
+
+A wizard’s connections belong to the person who runs it. A plugin that works for the whole
+space, such as a calendar that every booking wizard reads, connects an account of its own with
+`server.connections`. It uses the runtime’s built-in connectors (Google, Microsoft, Slack,
+GitHub, HubSpot, S3 …). The runtime keeps the tokens and keys sealed in the tenant’s database and
+refreshes the tokens.
+
+```ts
+const ACTIONS = ["list_events", "create_event", "delete_event"];
+
+// Which of them can be signed in to on this runtime now.
+const offered = await server.connections.available(["google-calendar", "microsoft-outlook"]);
+
+// The provider's sign-in page, for a route of the plugin to hand to its studio half.
+const { url } = await server.connections.start({ space, connector: "google-calendar", actions: ACTIONS });
+
+// Later, in a route, a tool or a job:
+const [account] = await server.connections.list(space);
+const { events } = await server.connections.call<{ events: unknown[] }>(account.id, "list_events", {
+  time_min: from,
+  time_max: to,
+});
+```
+
+| `server.connections.` | Does |
+|---|---|
+| `available(ids)` | Returns the connectors of these ids that a person can connect here now: `{ id, name, auth }`, and for `auth: "api_key"` the `fields` to ask for (`key`, `label`, `placeholder`, `required`, `secret`). An OAuth connector is offered once its client is set up (`GOOGLE_OAUTH_CLIENT_ID` …) or when it registers a client itself. On a local install Google is also offered through the linked engenty account. A connector that takes keys (HubSpot, S3) is always offered |
+| `start({ space, connector, actions, lang? })` | Returns the provider’s sign-in page of an OAuth connector. The provider asks only for the rights that `actions` need. `lang` (`"en"` or `"de"`) is the language of the page the person comes back to; without it, the page follows their browser |
+| `connect({ space, connector, actions, credentials })` | Connects a connector that takes keys. `credentials` holds the keys by field key. The runtime tries them once at the provider and then keeps them sealed. Keys the provider refuses throw an error with the status `400` and the code `credentials`, whose message says what was wrong. Returns the connection |
+| `list(space)`, `get(id)` | Return what is connected: `{ id, space, connector, label, actions, createdAt }`, the newest first. `label` is the account as the provider names it, often an email address |
+| `call(id, action, input)` | Runs one of the connector’s actions with the account. When the token has run out, the runtime fetches a fresh one first |
+| `remove(id)` | Forgets the connection and its tokens |
+
+## Signing in
+
+`start` returns an address. Open it in a window from the studio half. The provider sends the
+person back to the runtime (`/api/connect/callback`, the address a wizard’s connections use too).
+The runtime keeps the account under the plugin and the space. The window then posts
+`{ type: "wizards:connected", ok }` to the studio and closes:
+
+```tsx
+const { url } = await studio.api.post<{ url: string }>(`/connect?space=${space.id}`);
+window.open(url, "connect", "width=520,height=700");
+
+window.addEventListener("message", (event) => {
+  if (event.data?.type === "wizards:connected" && event.data.ok) {
+    refetch();
+  }
+});
+```
+
+- A second sign-in to the same account for the same space replaces the first one’s tokens and
+  actions. It does not add a second connection.
+- A local install without a Google client of its own connects Google through the linked
+  engenty account. Without a linked account, `start` throws an error with the status `409` and
+  the code `account`, whose message says what to do.
+
+## What `call` refuses
+
+- An action the connection was not made for. Connect again with that action in `actions`.
+- What the provider refuses. `call` throws the provider’s error, with the status and the first
+  words of its answer. If the person removed the connection at the provider, the next call
+  fails this way.
+
+## Where it is kept
+
+The connections are kept in the table `plugin_connection` of the tenant’s database, by plugin
+and space. A plugin sees only its own connections. Deleting a space deletes them. Unloading or
+removing the plugin leaves them in place.

package/apps/runtime/dist/docs/dev/plugins/events.md

@@ -0,0 +1,89 @@
+---
+title: Events
+description: Do something when a run ends or a space changes – keep who it was, post a message, read a new document.
+version: 0.5.0
+---
+
+A plugin can listen to runs that reach their end, and to spaces that change.
+
+```ts
+// A real run ended: keep who it was.
+server.on("run.done", async ({ run, wizard, values }) => {
+  const email = typeof values.email === "string" ? values.email.trim().toLowerCase() : "";
+  if (run.mode !== "live" || !email) {
+    return;
+  }
+  const seen = {
+    name: typeof values.name === "string" ? values.name : null,
+    wizard: wizard.title,
+    seenAt: new Date(),
+  };
+  await db()
+    .insert(person)
+    .values({ email, ...seen })
+    .onConflictDoUpdate({ target: person.email, set: seen });
+});
+```
+
+## Events
+
+| Event | A run |
+|---|---|
+| `run.done` | reached its result |
+| `run.failed` | stopped with an error |
+| `run.cancelled` | was cancelled |
+
+| Event | A space | Gets |
+|---|---|---|
+| `space.created` | was made here, or arrived from engenty wizards on someone’s computer | `{ space: { id } }` |
+| `space.updated` | changed its name, its brand (Info & brand), its facts or its connected systems, or arrived again from a computer | `{ space: { id } }` |
+| `space.deleted` | was deleted | `{ space: { id } }` |
+| `space.file.ready` | has a file that was read: a document is in the index now | `{ space: { id }, file: { id, name, kind, mime } }` |
+| `space.file.removed` | lost a file | `{ space: { id }, file: { id, name, kind, mime } }` |
+
+`file.kind` is `"document"`, `"logo"`, `"asset"` or `"pattern"`.
+
+```ts
+// A document arrived: read it into the wiki.
+server.on("space.file.ready", async ({ space, file }) => {
+  if (file.kind === "document") {
+    await queue(space.id, file.id);
+  }
+});
+```
+
+Nothing waits for the space events: the request that changed the space answers before its
+listeners are done.
+
+## What a run listener gets
+
+| | |
+|---|---|
+| `run.id`, `run.wizardId` | The run and its wizard |
+| `run.mode` | `"live"`: a real run, over the wizard’s link or from an AI app. `"test"`: a test run |
+| `run.status` | `"done"`, `"failed"` or `"cancelled"` |
+| `wizard` | `{ id, title, projectId }` |
+| `values` | What the person answered, by field id |
+
+`values` holds the answers as the wizard asked for them. Which fields exist depends on the
+wizard. A listener that wants an email address looks for a field with the id it expects and does
+nothing when it is missing. Check the type of every value you use.
+
+## Rules a listener runs under
+
+- **It runs inside the run’s tenant.** `server.getTenantDb()` is that tenant’s database.
+- **It runs after the run ended.** A listener cannot change the run or its result.
+- **It cannot fail the run.** A listener that throws is logged with the plugin’s id.
+- **It can be called twice.** A finished run that is redone and ends again fires the event
+  again. Write listeners so that a second call does no harm: update a row instead of adding one,
+  or remember the run’s id.
+- **Nothing waits for it.** Give outside calls a time limit:
+
+  ```ts
+  await fetch(url, { method: "POST", body, signal: AbortSignal.timeout(10_000) });
+  ```
+
+## Test runs
+
+Test runs fire the same events with `run.mode === "test"`. A plugin that keeps data about real
+people, or tells someone outside, leaves test runs out, as the example above does.

package/apps/runtime/dist/docs/dev/plugins/examples.md

@@ -0,0 +1,101 @@
+---
+title: Examples
+description: Two plugins in the repository to read, run and copy.
+version: 0.5.0
+---
+
+The repository has two example plugins. Load them from a checkout with one line in `.env.local`:
+
+```bash
+PLUGINS_DIR=examples/plugins
+```
+
+## notify: one file
+
+[examples/plugins/notify.ts](https://github.com/engenty/wizards/blob/main/examples/plugins/notify.ts)
+posts a line to an address whenever a real run of a wizard reaches its end.
+
+```ts
+import type { WizardsPluginFactory } from "@engenty/wizards/plugin";
+
+const plugin: WizardsPluginFactory = (wizards) => {
+  const url = wizards.config.get("NOTIFY_URL");
+  if (!url) {
+    wizards.log.warn("NOTIFY_URL is not set: nothing will be sent.");
+    return;
+  }
+  wizards.server.on("run.done", async ({ run, wizard }) => {
+    if (run.mode !== "live") {
+      return;
+    }
+    await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ wizard: wizard.title, run: run.id }),
+      signal: AbortSignal.timeout(10_000),
+    });
+  });
+};
+
+export default plugin;
+```
+
+| It shows | |
+|---|---|
+| A plugin of one file | Its id is the file’s name |
+| A setting | `NOTIFY_URL` in the install’s `.env`, read at load time |
+| A listener | Test runs left out, a time limit on the call |
+
+## run-log: both halves
+
+[examples/plugins/run-log](https://github.com/engenty/wizards/tree/main/examples/plugins/run-log)
+keeps a line for every run that ended and shows them in the studio.
+
+| File | Shows |
+|---|---|
+| `engenty.plugin.json` | A manifest |
+| `migrations/0001_init.sql` | A table, `run_log_entry`, with an index |
+| `migrations/0002_space.sql` | A column added later: the space of each line |
+| `src/schema.ts` | The same table for Drizzle |
+| `src/plugin.ts` | A listener on the three run events (`run.done`, `run.failed`, `run.cancelled`), two routes (one for admins only, one that filters by space) and a tool, `run-log.recent` |
+| `ui/messages.ts` | Its texts in English and German |
+| `ui/plugin.tsx` | A section of the space page under Results with the space’s last runs, a page with the whole log, and a settings section that empties the log |
+| `package.json` | A workspace package whose `build` script builds the studio half |
+
+Build its studio half once, or on every save:
+
+```bash
+node scripts/build-plugin.mjs examples/plugins/run-log
+```
+
+```bash
+node scripts/build-plugin.mjs examples/plugins/run-log --watch
+```
+
+Then, in the studio:
+
+1. Test a wizard to its end.
+2. Open the space’s Results: choose “Results” under Space in the sidebar, or open the space’s
+   page with the house icon in the app bar and go to Results. “Runs” stands below the results
+   and shows the last five runs of the space’s wizards. Its last line, “All … runs”, opens the
+   page with the whole log.
+3. Settings → Runs shows how many lines are kept, and “Delete all” deletes them.
+4. An AI step can list the tool “Run log” and tell how the last runs ended.
+
+## The plugin of these pages
+
+The `contacts` plugin these pages build up, piece by piece:
+
+| Piece | Page |
+|---|---|
+| The table `contacts_person` | [Tables](./tables.md) |
+| The listener that keeps who ran a wizard | [Events](./events.md) |
+| The routes that list and remove contacts | [Routes](./routes.md) |
+| The tool `contacts.lookup` | [Tools](./tools.md) |
+| The page and the settings section | [The studio half](./studio.md) |
+
+## Tests to read
+
+[apps/runtime/test/plugins.test.ts](https://github.com/engenty/wizards/blob/main/apps/runtime/test/plugins.test.ts)
+writes small plugins into a folder and exercises them: finding, loading, a plugin that fails,
+routes, tables per tenant, tools in a run, events and reloading.

package/apps/runtime/dist/docs/dev/plugins/index.md

@@ -0,0 +1,78 @@
+---
+title: Plugins
+description: What a plugin is, what its two halves can add, and what it may touch.
+version: 0.5.0
+---
+
+A plugin adds to a runtime without changing its code. The runtime finds plugins when it starts,
+loads them from their files and loads a plugin again when its files change.
+
+## What a plugin can add
+
+| It adds | Where it shows | Page |
+|---|---|---|
+| A tool for AI steps | In a step’s tool list, in the assistant’s and the MCP authoring guide | [Tools](./tools.md) |
+| A runner: a door a wizard runs through, with the run API that drives runs from it | In the share dialog’s channels, at `/w/<token>/<runner>`, on the wizard’s first page | [Runners](./runners.md) |
+| A runner’s settings and setup in the share dialog | In the share dialog, behind its gear and behind “Set up” in the runner’s row | [Runners](./runners.md#the-runners-part-of-the-share-dialog) |
+| A block and tools for every AI step of a space | In the steps’ instructions | [The space](./space.md) |
+| Pages, tables and files of a space’s Knowledge, with their categories | In Knowledge, and in what `project_search` finds | [The space](./space.md#knowledge-a-plugin-writes) |
+| Texts in a space’s search index | In what `project_search` finds | [The space](./space.md#the-search-index) |
+| Tools of the studio’s assistant, and their cards | In the assistant’s chat, on every page. For now the assistant is off unless it is switched on | [The space](./space.md#tools-of-the-space-assistant) |
+| Routes | Below `/api/studio/plugins/<id>`, for programs with a key below `/api/v1/plugins/<id>`; public ones below `/api/public/plugins/<id>`, one for every tenant below `/api/public/plugins/<id>/shared` | [Routes](./routes.md) |
+| Tables | In every tenant’s database | [Tables](./tables.md) |
+| A listener on runs that end and spaces that change | Nowhere: it works in the background | [Events](./events.md) |
+| A job, again and again | Nowhere: it works in the background | [The server half](./server.md#jobs) |
+| The team’s own number for texts and calls, on engenty.ai | Where the plugin’s runner and pages use it | [The server half](./server.md#numbers-of-the-manage-app) |
+| An account of a space (a calendar, a mailbox), signed in through a built-in connector | Where the plugin’s own pages offer it | [Accounts](./connections.md) |
+| A wizard as a template | First among the templates of a new wizard, and in the MCP `list_starters` | [Starters](./starters.md) |
+| A page of the studio | Behind an icon in the app bar, or at its address | [The studio half](./studio.md) |
+| A section of the settings | In the settings’ list | [The studio half](./studio.md) |
+| A section of the space page | In one of its parts, below the part’s own sections | [The studio half](./studio.md#the-space) |
+| A part of the space page | In the space’s menu, beside Info & brand, Knowledge, Data and Results | [The studio half](./studio.md#a-part-of-the-plugins-own) |
+
+## Two halves
+
+| | Server half | Studio half |
+|---|---|---|
+| File | `src/plugin.ts`, or the one file a small plugin is | `ui/plugin.tsx`, built to `dist/client.js` and `dist/client.css` |
+| Runs in | The runtime | The studio, after sign-in |
+| Loaded | As TypeScript, no build | As the built script |
+| Types | `@engenty/wizards/plugin` | `@engenty/wizards/plugin/studio` |
+| Adds | Tools, runners, routes, tables, listeners, jobs, starters, accounts, Knowledge, the space’s block, index and assistant tools | Pages, icons in the app bar, sections of the settings and of the space page, parts of the space page, a runner’s settings and setup in the share dialog, cards in the assistant’s chat |
+
+A plugin has one half or both. The studio half talks to the server half over the plugin’s own
+routes.
+
+```mermaid
+flowchart LR
+  page["Studio half, in the browser<br/>ui/plugin.tsx<br/>pages, app bar, settings"]
+  runner["The runtime's step runner"]
+  server["Server half, in the runtime<br/>src/plugin.ts<br/>tools, routes, listeners"]
+  db[("Tenant database<br/>the plugin's tables")]
+  page -- "the plugin's routes" --> server
+  runner -- "calls a tool, says a run ended" --> server
+  server --> db
+```
+
+## What a plugin may touch
+
+A plugin runs inside the runtime’s process with all of its rights. It can read every tenant’s
+data, the install’s settings and the files of the computer it runs on. There is no sandbox and
+no permission list.
+
+- Install only code you know.
+- A plugin for others says in its own description what it reads and where it sends it.
+
+## Not the Claude Code plugin
+
+The “Claude Code plugin” of engenty wizards is something else: it is what a runtime hands to
+Claude Code (`plugin/` in the repository). These pages are about plugins of the runtime.
+
+## Not there yet
+
+- A plugin can’t bring connectors of its own, or tools for MCP clients and AI apps. It connects
+  accounts through the built-in connectors: [Accounts](./connections.md).
+- A plugin can’t add new kinds of steps or fields: the public pages of a wizard load no plugin.
+  A plugin’s runner is served whole at its own sub-path; nothing is loaded into the page or the
+  chat.
+- You can’t build a studio half without a checkout of the repository.

package/apps/runtime/dist/docs/dev/plugins/layout.md

@@ -0,0 +1,90 @@
+---
+title: Files and manifest
+description: Where the runtime looks for plugins, what counts as one, and what engenty.plugin.json says.
+version: 0.5.0
+---
+
+## Where the runtime looks
+
+| Folder | What is in it |
+|---|---|
+| `modules/` of the runtime | Plugins that ship with engenty wizards |
+| Each folder of `PLUGINS_DIR` (comma-separated) | Plugins of this install |
+
+- An installed app looks in `~/.engenty/wizards/plugins` unless its `.env` names another folder.
+- In a checkout `PLUGINS_DIR` is empty. `PLUGINS_DIR=examples/plugins` in `.env.local` loads
+  the examples.
+- A runtime that watches its plugins creates a folder of `PLUGINS_DIR` that is missing.
+
+## What counts as a plugin
+
+In such a folder:
+
+| Entry | Is |
+|---|---|
+| `notify.ts`, `notify.js` | A plugin of one file. Its id is the file’s name |
+| `contacts/engenty.plugin.json` | A plugin with a manifest |
+| `hello/index.ts`, `hello/index.js` | A plugin without a manifest. Its id is the folder’s name |
+| `node_modules/<package>`, `node_modules/@scope/<package>` | Installed packages that carry a manifest |
+
+- The runtime skips names that begin with `.` or `_`.
+- It doesn’t read `.mjs` files: Node keeps such a file once it is imported, so it could not load
+  again.
+- Of two plugins with the same id, the first one found stays. The other shows under “Not a
+  plugin” in Settings → Plugins, as does a manifest that cannot be read.
+
+## A plugin’s folder
+
+```
+contacts/
+  engenty.plugin.json     the manifest
+  src/
+    plugin.ts             the server half
+    schema.ts             its tables, for Drizzle
+  migrations/
+    0001_init.sql         the tables, as SQL
+  ui/
+    plugin.tsx            the studio half, as you write it
+  dist/
+    client.js             the studio half, built
+    client.css
+  package.json            only if it has dependencies of its own
+```
+
+Only the manifest is required. A plugin with a studio half must be a folder with a manifest.
+
+## The manifest
+
+`engenty.plugin.json` is the same file an engenty module has. The runtime keeps fields it
+doesn’t know as they are.
+
+```json
+{
+  "id": "contacts",
+  "name": "Contacts",
+  "version": "0.1.0",
+  "description": "Keeps the email address of everyone who ran a wizard to its end."
+}
+```
+
+| Field | | Default |
+|---|---|---|
+| `id` | Lower case, digits and `-`, starting with a letter, at most 40 characters. Part of the plugin’s addresses and of its tools’ ids | required |
+| `name` | Shown in the settings | required |
+| `version` | Shown in the settings | `0.0.0` |
+| `description` | Shown in the settings | |
+| `server` | The server half, from the plugin’s folder | `src/plugin.ts`, then `src/plugin.js`, then `dist/plugin.js` |
+| `studio` | The built studio half | `dist/client.js` |
+| `styles` | The built studio half’s styles | `dist/client.css` |
+
+A path in the manifest must stay inside the plugin’s folder.
+
+## Dependencies
+
+| The plugin imports | It comes from |
+|---|---|
+| `@engenty/wizards/plugin`, `@engenty/wizards/plugin/thread`, `zod`, `drizzle-orm`, `drizzle-orm/sqlite-core` | The runtime’s own copies, wherever the plugin’s file is |
+| Its own files | Beside it, as TypeScript |
+| Anything else | A `node_modules` the plugin brings beside it |
+
+For the studio half see [The studio half](./studio.md#what-the-studio-shares).