@engenty/wizards-runtime 0.7.6 → 0.7.8

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

@@ -0,0 +1,36 @@
+---
+title: Integration
+description: Bring a published wizard into other systems – for people, for AI apps and for your own code.
+version: 0.7.4
+---
+
+A published wizard runs wherever a person can reach it. These pages show how to bring it into
+other systems, from a plain link to a chat that starts the wizard by itself.
+
+## For people
+
+| | |
+|---|---|
+| [Link and QR code](./link-and-share.md) | The wizard’s own page, as a link or a QR code |
+| [Embed](./embed.md) | The wizard on your website, inline, as a button or a chat |
+| [WordPress](./wordpress.md) | The plugin “engenty wizards” places wizards and reads their results |
+| [Channels](./channels.md) | A chat, a conversation or a call, and WhatsApp, SMS or the phone |
+
+## For AI apps
+
+| | |
+|---|---|
+| [MCP](./mcp.md) | AI apps list, run and build wizards over the Model Context Protocol |
+| [MCP Apps](./mcp-apps.md) | AI apps that support MCP Apps show the wizard itself, page by page |
+| [Claude Code plugin](./claude-code-plugin.md) | The `/wizard` command and the skills to build and use wizards |
+| [OpenUI](./openui.md) | A chat built with OpenUI runs the wizard inside the conversation |
+
+## For your code
+
+| | |
+|---|---|
+| [Your own UI](./own-ui.md) | Your app draws the run with `@engenty-wizards/runner` |
+| [Results to your systems](./results.md) | What a run produces goes on to your own systems |
+
+Each way starts from a published wizard. [Test and share](../../user/test-and-share.md) in the
+user guide explains how you publish one.

package/apps/runtime/dist/docs/dev/integration/link-and-share.md

@@ -0,0 +1,10 @@
+---
+title: Link and QR code
+description: Hand out a published wizard as a link or a QR code.
+version: 0.7.4
+---
+
+This page is not written yet.
+
+Until then, [Share](../../user/test-and-share.md#share) in the user guide describes the link, the
+QR code and who can open them.

package/apps/runtime/dist/docs/dev/integration/mcp-apps.md

@@ -0,0 +1,10 @@
+---
+title: MCP Apps
+description: AI apps that support MCP Apps show the wizard itself as a widget, page by page.
+version: 0.7.4
+---
+
+This page is not written yet.
+
+Until then, [What an app can do](../../user/ai-apps.md#what-an-app-can-do) in the user guide lists
+what an app with MCP Apps shows.

package/apps/runtime/dist/docs/dev/integration/mcp.md

@@ -0,0 +1,10 @@
+---
+title: MCP
+description: AI apps list, run and build wizards over the Model Context Protocol.
+version: 0.7.4
+---
+
+This page is not written yet.
+
+Until then, [AI apps](../../user/ai-apps.md) in the user guide shows how you add engenty wizards
+to Claude Desktop, Cursor, Codex and other AI apps.

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

@@ -0,0 +1,20 @@
+{
+  "title": "Integration",
+  "defaultOpen": true,
+  "pages": [
+    "index",
+    "---For people---",
+    "link-and-share",
+    "embed",
+    "wordpress",
+    "channels",
+    "---For AI apps---",
+    "mcp",
+    "mcp-apps",
+    "claude-code-plugin",
+    "openui",
+    "---For your code---",
+    "own-ui",
+    "results"
+  ]
+}

package/apps/runtime/dist/docs/dev/integration/openui.md

@@ -0,0 +1,181 @@
+---
+title: Wizards in OpenUI chats
+description: A Wizard component for OpenUI’s React renderer. The chat’s model decides that a wizard runs, and the wizard runs its own pages inside the conversation.
+version: 0.7.4
+---
+
+A chat built with [OpenUI](https://github.com/thesysdev/openui) composes its answers as it
+goes: cards, charts, forms and buttons, whatever the model finds fitting. A wizard is the one
+thing in such a chat that runs the same way every time, with the pages, steps and result its
+author defined. `@engenty/wizards/openui` puts the two together: the chat decides that a wizard
+fits and what it already knows, the wizard then runs inside the conversation, and the chat
+hears the result.
+
+It is part of `@engenty/wizards`, the package for code outside engenty wizards
+([`packages/wizards/src/openui`](https://github.com/engenty/wizards/tree/main/packages/wizards/src/openui)
+in the repository, under the MIT licence). A whole chat to try it with is `examples/openui-chat`.
+
+## What OpenUI is
+
+OpenUI (Thesys, MIT) is a way to let a model draw. Three parts matter here:
+
+- **A language the model writes.** An answer is a short program: `root = Card([…])` with
+  components as calls, such as `TextContent("…")` or `Form(…)`. The model streams it like text.
+- **A React renderer** (`@openuidev/react-lang`) that parses the program as it streams and draws
+  it with a **component library**: React components with a name, a description and typed props.
+- **A chat kit** (`@openuidev/react-ui`): the library of chat components, the thread, the
+  composer and an `AgentInterface` that puts them together.
+
+The model learns the language from the system prompt the library makes. The chat library’s
+prompt is about 14,000 tokens: every component with its props and description, the rules, and
+5 worked examples of whole answers. The model imitates the examples. Nothing in that prompt is
+a fixed flow: every answer, and every form in it, is composed anew.
+
+A wizard is the only fixed definition in such a chat. The model writes one line, and from then
+on the wizard’s pages, AI steps, review and result run as its author defined them.
+
+## How the Wizard component works
+
+```mermaid
+sequenceDiagram
+    participant S as Chat server
+    participant M as Model
+    participant B as Browser (OpenUI renderer)
+    participant R as Runtime
+    S->>R: GET /api/public/wizards/:token
+    R-->>S: title, description, fields
+    S->>M: system prompt + wizard rules
+    M-->>B: root = Card([TextContent("…"), Wizard("<token>", "<note>", {plate: "W-12345"})])
+    B->>R: POST /api/public/wizards/:token/runs
+    R-->>B: run id
+    loop every step
+        R-->>B: the run’s view (stream)
+        B->>R: a page’s answers, a review, back
+    end
+    B->>S: continue_conversation: “The wizard finished.” + result
+    S->>M: the thread
+    M-->>B: an answer in plain words
+```
+
+It has two halves, one for each side of the chat.
+
+### The server half
+
+`@engenty/wizards/openui/server` draws nothing, so a server can import it alone.
+
+```ts
+import { addWizard, loadWizards, wizardRules } from "@engenty/wizards/openui/server";
+import { openuiChatLibrary, openuiChatPromptOptions } from "@openuidev/react-ui/genui-lib";
+
+const wizards = await loadWizards("http://localhost:24368", ["<token>", "<token>"]);
+const prompt = addWizard(openuiChatLibrary).prompt({
+  ...openuiChatPromptOptions,
+  additionalRules: [...(openuiChatPromptOptions.additionalRules ?? []), ...wizardRules(wizards)],
+});
+```
+
+- `loadWizards(runtimeUrl, tokens)` reads each published wizard from the runtime
+  (`GET /api/public/wizards/:token`): its title, description and the fields its pages ask, in
+  order. A wizard the runtime does not answer for is left out, so the chat keeps working when
+  one is unpublished.
+- `addWizard(library)` extends an OpenUI library with the Wizard component, among a Card’s
+  children. Its prompt then has `Wizard(wizard: string, note?: string, prefill?: …)`.
+- `wizardRules(wizards)` are the rules that go with it: when to answer with a wizard, that the
+  wizard asks its own questions (never a Form in its place), what may be prefilled, and the list
+  of wizards with their tokens and fields.
+
+With that, the model answers a fitting request with a Card that holds one short text and
+`Wizard("<token>", "<note>", {prefill})`. The prefill holds answers the person already gave in
+the conversation, by field id; the person still sees and sends each page.
+
+### The component, in the browser
+
+```tsx
+import "@engenty/wizards/openui/styles.css";
+import { addWizard, configureWizards, Wizard } from "@engenty/wizards/openui";
+import { openuiChatLibrary } from "@openuidev/react-ui/genui-lib";
+
+configureWizards({ runtime: "/wizards-runtime" });
+const library = addWizard(openuiChatLibrary, Wizard);
+```
+
+- `configureWizards({ runtime })` names the runtime once, as the browser reaches it: a path the
+  host proxies to it, or the runtime’s address. A proxy on the host’s own address keeps the
+  runner’s visitor cookie first-party. `lang` sets the language of the runner’s own words
+  (`en` unless given), `Mascot` draws the wizard’s mascot above its pages.
+- `addWizard(library, Wizard)` is the same extension as on the server, with the drawing
+  component. Both make the same prompt.
+
+The component draws the run with the runner, the same code as the wizard’s own page
+(`packages/runner`), in styles scoped to `.engenty-runner`, so the chat’s styles and the
+runner’s never meet. Every field kind works as on the wizard’s own page, the camera and the
+signature included. The page is not a frame, so nothing else is needed for them.
+
+What happens in the message:
+
+1. **The run starts** once the model’s line has finished streaming, so a half-written token never
+   starts a run: `POST /api/public/wizards/:token/runs`, as a visitor of the runtime.
+2. **The run id stays with the message**, in the state OpenUI keeps for it. A message shown again
+   continues the same run.
+3. **The run shows live** over the runtime’s stream of the run’s view (`/api/runs/:id/stream`), and
+   the person’s answers go to the run’s routes (`/api/runs/:id/pages/:step`, `…/reviews/:step`,
+   `…/back`, `…/retry`). These are the routes the wizard’s own page uses.
+4. **The result goes back to the chat.** When the component sees the run finish, it sends OpenUI’s
+   `continue_conversation` action: a turn of the person that says the wizard finished, with the
+   result as context for the model: the wizard’s title, the run id and the texts of the result
+   steps, each cut at 4,000 characters. The model answers in plain words.
+
+The chat hears of a run it saw finish. A message shown again with a done run shows the result
+and tells the chat nothing new.
+
+### Who runs, who pays
+
+The browser talks to the runtime as a visitor, as on the wizard’s own page: the runtime sets a
+visitor cookie, lets a visitor start 6 runs an hour
+([`LIMIT_VISITOR_RUNS_PER_HOUR`](../../user/command-line.md#settings)) and spends the wizard’s own
+credits or model keys. The chat’s model and the wizards’ model are two different things: the
+chat picks the model that writes its answers, and each wizard’s steps run on what its space
+has.
+
+## Try it
+
+`examples/openui-chat` is an OpenUI chat (`AgentInterface`) with any OpenAI-compatible model,
+the wizards it may start and a proxy to the runtime. In short:
+
+1. Start the runtime from a checkout (`pnpm dev`) and publish a wizard or two in the studio.
+   Each one’s token is the part of its link after `/w/`.
+2. Put an `.env.local` in `examples/openui-chat`: `WIZARDS=<token>,<token>`, `CHAT_BASE_URL`,
+   `CHAT_API_KEY` and `CHAT_MODEL` for the chat’s model.
+3. `pnpm --filter @engenty-wizards/example-openui-chat dev` and open `http://localhost:5190`.
+4. Ask for something a wizard does, in your own words.
+
+The example’s README has the details, the endpoints that work and what to set while you try
+things.
+
+## Exports
+
+| From | Export | What it is |
+|---|---|---|
+| `@engenty/wizards/openui/server` | `loadWizards(runtimeUrl, tokens)` | The published wizards behind the tokens, as `WizardInfo[]` |
+| | `wizardRules(wizards)` | The rules a system prompt adds |
+| | `addWizard(library, component?)` | The library with the Wizard component among a Card’s children |
+| | `WizardSpec`, `wizardProps`, `WizardProps` | The component as a prompt sees it, and its props |
+| | `WIZARD_COMPONENT`, `WIZARD_DESCRIPTION` | Its name and description |
+| `@engenty/wizards/openui` | all of the above | |
+| | `configureWizards(config)` | Names the runtime, the language and the mascot |
+| | `Wizard` | The drawing component |
+| | `useWizardRun(runId, prefill)` | One run, live, for a host that draws runs itself |
+| `@engenty/wizards/openui/styles.css` | | The runner’s styles, scoped to the wizard |
+
+`@openuidev/react-lang`, `react`, `react-dom` and `zod` are peer dependencies: the chat brings
+them. The package is written against `@openuidev/react-lang` 1.0 and the chat kit
+`@openuidev/react-ui` 0.18.
+
+## Good to know
+
+- **One runtime per page.** `configureWizards` names it once, before the first render.
+- **Other hosts.** The component sits on the runtime’s public run routes, not on OpenUI’s
+  internals. A host with its own components can draw a run with `useWizardRun` and the runner’s
+  parts, and another UI format can follow the same way.
+- **OpenUI’s Inspect button** at the bottom right of a page in development is OpenUI’s own
+  (`@openuidev/react-lang` adds it and loads it from jsDelivr). A production build leaves it out.

package/apps/runtime/dist/docs/dev/integration/own-ui.md

@@ -0,0 +1,10 @@
+---
+title: Your own UI
+description: Draw a wizard’s run in your own app with @engenty-wizards/runner and the runtime’s public run routes.
+version: 0.7.4
+---
+
+This page is not written yet.
+
+Until then, [OpenUI](./openui.md) shows one app that does it: it draws the run with
+`@engenty-wizards/runner` (`packages/runner`) over the runtime’s public run routes.

package/apps/runtime/dist/docs/dev/integration/results.md

@@ -0,0 +1,11 @@
+---
+title: Results to your systems
+description: Send what a run produces to your own systems.
+version: 0.7.4
+---
+
+This page is not written yet.
+
+Until then, [Results, contacts, appointments](../../user/wordpress.md#results-contacts-appointments)
+shows how the WordPress plugin receives results. A plugin can also answer other services with
+its own [routes](../plugins/routes.md).

package/apps/runtime/dist/docs/dev/integration/wordpress.md

@@ -0,0 +1,10 @@
+---
+title: WordPress
+description: Put published wizards on a WordPress site with the plugin “engenty wizards”.
+version: 0.7.4
+---
+
+This page is not written yet.
+
+Until then, [WordPress](../../user/wordpress.md) in the user guide shows how you connect a site,
+place a wizard and read its results in the admin.

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

@@ -3,5 +3,5 @@
   "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"]
+  "pages": ["index", "wizard-format", "plugins", "integration"]
 }

package/apps/runtime/dist/docs/user/command-line.md

@@ -11,7 +11,7 @@ version: 0.5.0
 | `wizards` | Shows what is running, and a menu. While it runs, you can open the studio, restart or stop it; while it doesn’t, “Start in the background” or “Start in this terminal”. Then “Update”, which restarts it into the new version, “Start at login”, “Connect AI apps”, “Account”, “Status”, “Setup”, “Uninstall” and “Help”. The first time, the setup runs first. It needs a terminal |
 | `wizards start` | Starts it and opens the studio. It runs in that terminal, and Ctrl-C stops it. The first time, the setup runs first |
 | `wizards studio` | Opens the studio in your browser. If it isn’t running, it starts in the background first |
-| `wizards setup` | Runs the guided setup again: your account, an AI client, the browser and ffmpeg, start at login, your AI apps. `--local` leaves the account out ([Local only](./local-only.md)) |
+| `wizards setup` | Runs the guided setup again: your account, an AI client, the browser and ffmpeg, a decision model, start at login, your AI apps. `--local` leaves the account out ([Local only](./local-only.md)) |
 | `wizards account` | Shows the account this computer is signed in to: who, which team, the credits. `sign-in` shows a link and a code and opens your browser; `sign-out` disconnects this computer |
 | `wizards open` | Signs this browser in to the running studio. `--print` only prints the link; it works once, within a minute |
 | `wizards status` | Shows what is installed and running, with the browser it uses for PDF, PNG and websites |

package/apps/runtime/dist/docs/user/install.md

@@ -32,6 +32,7 @@ have is left alone), installs engenty wizards into `~/.engenty/wizards` (about 6
 | Your engenty account | Asks “Sign in or create your account now?”. If you say yes, it shows a link and a code and opens your browser for the sign-in at account.engenty.ai; check that the page shows the same code (if you have no account yet, the page creates one with your invitation code, or puts you on the waitlist). While it waits, Enter opens the page again and Esc goes on without an account. Once you are signed in, what you publish on this computer runs in the cloud too. If you say no, `wizards account sign-in` does it any time. Setting it up again with `--local` signs an account out. `--local` leaves the account out altogether: see [Local only](./local-only.md) |
 | An AI client | Looks for Codex, Claude Code, Antigravity and Cursor Agent and offers to install the ones that are missing. It puts first the one whose app (ChatGPT, Claude, Antigravity, Cursor) is on your Mac, as you most likely have that subscription already. You can also use your account’s credits, an API key, [Ollama](https://ollama.com) or, on a Mac with Apple silicon and macOS 26, Apple Intelligence: the studio’s [first page](./first-start.md) offers them |
 | A browser and ffmpeg | Names the browser for PDF and PNG exports and steps on websites: the first of Chrome, Edge and Chromium it finds (on a Mac also Brave). engenty wizards uses that one; [`CHROME_PATH`](./command-line.md#settings) picks another. It also says whether ffmpeg is there for MP4 videos of animated widgets, and with Homebrew it offers to install it |
+| A decision model (optional) | Offers to install [Ollama](https://ollama.com) if it isn’t there and to download Cloudflare’s Clef-flash into it (about 11 GB). The wizards then make their decisions, such as which branch to take, on your computer, without a key or credits. On a Mac the Ollama app goes into Applications and, when it first starts, asks once for your Mac’s password to set up its `ollama` command (cancel works too); on Linux Ollama’s own installer runs, installs `zstd` if it is missing, and asks for your password |
 | Start at login (optional) | engenty wizards starts in the background when you log in, so links and AI apps can always reach it. It is a LaunchAgent on a Mac and a systemd user service on Linux |
 | Your AI apps (optional) | Offers to add your wizards to the [AI apps](./ai-apps.md) it finds, such as Claude Desktop, Cursor or Codex |
 | The command | If `~/.local/bin` is not on your PATH, it offers to add it in your shell’s settings file |

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

@@ -32,7 +32,9 @@ async function askSystemOne(input, signal) {
                 return readSystemOne(input.questions, await res.json());
             }
             if (!(RETRYABLE.has(res.status) && attempt < 2)) {
-                console.warn(`[decide] the decision model answered ${res.status}`);
+                const why = (await res.text().catch(() => "")).trim().slice(0, 300);
+                access.refused?.(res.status, why);
+                console.warn(`[decide] the decision model answered ${res.status}${why ? `: ${why}` : ""}`);
                 return {};
             }
         }

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

@@ -483,7 +483,7 @@ export async function runAgentStep(step, ctx) {
     }
     const resolved = await textModel(step.model ?? "high", { ...ctx.call, effort: step.effort });
     const uploads = await personUploads(ctx);
-    const { tools, assets, close } = await buildStepTools(step, ctx, resolved, uploads);
+    const { tools, assets, instructions, close } = await buildStepTools(step, ctx, resolved, uploads);
     // A step without tools of its own and without uploads: the run's device may answer it alone.
     attachTools(resolved, tools, step.tools.length === 0 && uploads.length === 0);
     try {
@@ -501,6 +501,7 @@ export async function runAgentStep(step, ctx) {
         const system = [
             groundRules(ctx),
             step.tools.includes("browser") ? BROWSER_RULES : "",
+            instructions ?? "",
             `Today is ${today(ctx)}.`,
             brandBlock(ctx),
             // Knowledge: what the space holds for its wizards, and how to find and read it.