@engenty/wizards-runtime 0.7.5 → 0.7.7

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

@@ -133,7 +133,7 @@ type AgentStep = {
                                 //   (fields name the keys later steps read). Use it where a model would only fetch and copy
                                 //   data (free appointment times) — it answers in a second instead of half a minute.
                                 //   String inputs are templates; a filled-in whole number or true/false is passed as one.
-  tools: ("web_search"|"web_fetch"|"browser"|"sandbox"|"image"|"http"|"pages")[]
+  tools: ("web_search"|"web_fetch"|"browser"|"sandbox"|"image"|"http"|"pages"|"code")[]
   mcp?: string[]                // ids of the project's MCP servers this step may use
   connections?: string[]        // ids of wizard connections this step may read (mail → mail_search, mail_read, mail_save)
   output: { format: "text"|"markdown"|"json", fields?: { id, kind: "text"|"number"|"list"|"table"|"yesno"|"choice"|"score", description, columns?: string[], options?: string[] }[], schema?: Schema, surface?: SurfaceComponent[] | true }
@@ -156,6 +156,10 @@ type AgentStep = {
 //   project_list (by categories), page_read / table_read / project_document (an item whole, by its path).
 // "pages" brings: page_read / page_write — Markdown pages of the space the wizard keeps for every run (notes, a log
 //   that grows with append), shown to the admin under Space → Data; page_read also reads Knowledge by path.
+// "code" brings: execute_typescript — the model writes one program that calls the step's other tools (not the browser) as
+//   functions: loops, Promise.all, filtering, sums; only its answer reaches the model. For many calls of one kind (fetch 30
+//   pages, read every row of a list, search a mailbox month by month). It needs other tools to call; a change the person
+//   must allow first is never made from a program.
 // "browser" brings: browser_open/read/click/type/select/scroll/press/back/wait, browser_screenshot (the model looks at the page),
 //   browser_run_fast (a decision model clicks through a page's mechanical part, where one is reached),
 //   browser_request_credentials (the PERSON types a login into the page — the model never sees it; sign-ins can be remembered),

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

@@ -36,6 +36,8 @@ const INHERITED = new Set([
     "SANDBOX",
     "SANDBOX_ENABLED",
     "SANDBOX_IMAGE",
+    "SANDBOX_ALLOW_HOSTS",
+    "SANDBOX_ENGINES_DIR",
     "PLUGINS_DIR",
     "PLUGINS_WATCH",
     "ACCOUNT_URL",

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

@@ -8,6 +8,7 @@ import { CLIENTS, nodeIsCurrent } from "./machine.js";
 import { mcp } from "./mcp.js";
 import { menu } from "./menu.js";
 import { logsCommand, reportCommand } from "./report.js";
+import { sandboxCommand } from "./sandbox.js";
 import { setup } from "./setup.js";
 import { open, start, studio } from "./start.js";
 import { autostart, restart, status, stop } from "./status.js";
@@ -40,6 +41,8 @@ ${line(`${command()} restart`, "restart it, e.g. to switch to a newly installed
 ${line(`${command()} update`, "install the latest version")}
 ${line(`${command()} autoupdate`, "updates by themselves: add on or off (WIZARDS_DISABLE_AUTOUPDATE=1 is off too)")}
 ${more("(downloaded in the background, used from the next start; never during a run)")}
+${line(`${command()} sandbox`, "the sandbox where AI steps run code, without Docker: add or remove")}
+${more("(agentOS unless you name another engine, about 340 MB; used from the next start)")}
 ${line(`${command()} autostart`, "start it when you log in to this computer: add on or off")}
 ${more("(macOS: a LaunchAgent; Linux: a systemd user service)")}
 ${line(`${command()} connect`, "add your wizards to your AI apps: every app found, or the ones you name:")}
@@ -70,6 +73,7 @@ function parse(argv) {
     const args = {
         command: "",
         value: "",
+        engine: "",
         apps: [],
         paths: [],
         json: false,
@@ -116,10 +120,13 @@ function parse(argv) {
         else if (arg.startsWith("-")) {
             return `Unknown option ${arg}.`;
         }
-        else if (["autostart", "autoupdate", "logs", "account"].includes(args.command) &&
+        else if (["autostart", "autoupdate", "logs", "account", "sandbox"].includes(args.command) &&
             !args.value) {
             args.value = arg;
         }
+        else if (args.command === "sandbox" && !args.engine) {
+            args.engine = arg;
+        }
         else if (["connect", "disconnect", "features"].includes(args.command)) {
             args.apps.push(arg);
         }
@@ -199,6 +206,8 @@ async function main(argv) {
             return autoUpdateCommand(paths, args.value);
         case "account":
             return accountCommand(paths, args.value, { yes: args.yes });
+        case "sandbox":
+            return sandboxCommand(paths, args.value, args.engine);
         case "connect":
         case "disconnect":
             return connectCommand(paths, args.apps, args.command === "disconnect");

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

@@ -0,0 +1,77 @@
+import { delimiter, dirname, join } from "node:path";
+import { ENGINE_PACKAGES, engineList, installEngine, installedVersion, removeEngine, } from "../sandbox/install.js";
+import { runtimePath } from "./environment.js";
+import { runLogged } from "./exec.js";
+import { findOnPath } from "./machine.js";
+import { busy, cmd, no, ok, tilde } from "./ui.js";
+/** What `sandbox add` installs when no engine is named. */
+const DEFAULT_ENGINE = "agentos";
+/** Where an engine goes: `SANDBOX_ENGINES_DIR/<name>`, else `engines/<name>` in the install's folder. */
+export const engineDirOf = (paths, name) => join(process.env.SANDBOX_ENGINES_DIR?.trim() || join(paths.home, "engines"), name);
+/** The engines installed here, with their versions and the versions this release installs. */
+export function installedEngines(paths) {
+    return Object.entries(ENGINE_PACKAGES).flatMap(([name, engine]) => {
+        const version = installedVersion(engineDirOf(paths, name));
+        return version ? [{ name, label: engine.label, version, current: engine.version }] : [];
+    });
+}
+/**
+ * `wizards sandbox [add|remove] [engine]`: the sandbox where AI steps run code, without Docker.
+ * The engines are not part of engenty wizards; `add` downloads one beside the install.
+ */
+export async function sandboxCommand(paths, value, engine = "") {
+    const name = engine.toLowerCase() || DEFAULT_ENGINE;
+    if ((value === "add" || value === "remove") && !ENGINE_PACKAGES[name]) {
+        console.error(`${no} There is no engine “${name}”. ${engineList()}`);
+        return 2;
+    }
+    if (value === "add") {
+        return add(paths, name);
+    }
+    if (value === "remove") {
+        removeEngine(engineDirOf(paths, name));
+        console.log(`${ok} The sandbox ${ENGINE_PACKAGES[name].label} is removed. It goes away with the next ${cmd("restart")}.`);
+        return 0;
+    }
+    if (value) {
+        console.error(`Use ${cmd("sandbox add")} or ${cmd("sandbox remove")}.`);
+        return 2;
+    }
+    const installed = installedEngines(paths);
+    if (!installed.length) {
+        console.log(`${no} No sandbox is installed. AI steps can’t run code unless Docker has the engenty-sandbox image. To add one: ${cmd("sandbox add")}`);
+        return 0;
+    }
+    for (const { name, label, version } of installed) {
+        console.log(`${ok} The sandbox ${label} ${version} is in ${tilde(engineDirOf(paths, name))}.`);
+    }
+    console.log(`AI steps run code in ${installed.length === 1 ? "it" : "the first one"}, unless Docker has the engenty-sandbox image or SANDBOX names an engine.`);
+    return 0;
+}
+async function add(paths, name) {
+    const engine = ENGINE_PACKAGES[name];
+    const unsupported = engine.unsupported?.();
+    if (unsupported) {
+        console.error(`${no} ${unsupported}`);
+        return 1;
+    }
+    const npm = findOnPath("npm", [dirname(process.execPath), process.env.PATH ?? ""].join(delimiter));
+    if (!npm) {
+        console.error(`${no} npm wasn’t found next to this Node.js.`);
+        return 1;
+    }
+    const env = { ...process.env, PATH: runtimePath(paths, process.env) };
+    const logFile = join(paths.logs, "install.log");
+    const dir = engineDirOf(paths, name);
+    const spinner = busy(`Installing the sandbox (${engine.label} ${engine.version}, ${engine.size})…`);
+    try {
+        await installEngine(name, dir, (args) => runLogged(npm, args, { env, logFile }));
+    }
+    catch (err) {
+        spinner.fail(`The sandbox couldn’t be installed: ${err.message}`);
+        return 1;
+    }
+    spinner.stop(`${ok} The sandbox is installed in ${tilde(dir)}.`);
+    console.log(`AI steps run code in it from the next start: ${cmd("restart")}`);
+    return 0;
+}

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

@@ -6,6 +6,7 @@ import { autoUpdatePolicy, updateNotice } from "./autoupdate.js";
 import { installedByScript, isCheckout, packageRoot, packageVersion } from "./home.js";
 import { detectClients, findChrome, findFfmpeg, nodeIsCurrent } from "./machine.js";
 import { findWizardsProcesses, stopProcesses } from "./processes.js";
+import { installedEngines } from "./sandbox.js";
 import { entryUrl, runningRuntime, settings, startInBackground } from "./start.js";
 import { bad, badge, cmd, cyan, dim, no, ok, tilde } from "./ui.js";
 /**
@@ -45,6 +46,14 @@ export async function status(paths, checks) {
     }
     row("Browser", chrome ? `${ok} ${dim(tilde(chrome))}` : `${no} not found (needed for PDF and PNG)`);
     row("ffmpeg", ffmpeg.path ? `${ok} ${ffmpeg.version ?? ""}` : `${no} not found (needed for MP4)`);
+    const engines = installedEngines(paths);
+    row("Sandbox", engines.length
+        ? engines
+            .map(({ label, version, current }) => version === current
+            ? `${ok} ${label} ${version}`
+            : `${no} ${label} ${version} is outdated (${cmd("sandbox add")} installs ${current})`)
+            .join(", ")
+        : `${no} not installed (${cmd("sandbox add")} lets AI steps run code)`);
     const { updated, pending } = updateNotice(paths, packageVersion());
     if (updated) {
         console.log(`\n  ${ok} Updated to ${updated.to}. What changed: ${cyan(updated.notes)}`);

package/apps/runtime/dist/debug.js

@@ -8,6 +8,7 @@ import { logState, startedAt, tail } from "./log.js";
 import { managed } from "./manage.js";
 import { modelSettings } from "./models.js";
 import { loadedPlugins } from "./plugins/registry.js";
+import { sandboxEngine } from "./sandbox/index.js";
 import { runIndexOf, tenantOfRun } from "./tenants/control.js";
 import { LOCAL_TENANT } from "./tenants/tenant.js";
 /**
@@ -41,7 +42,7 @@ export async function status() {
         appUrl: env.appUrl,
         manageUrl: env.manage.url || null,
         gatewayUrl: (managed ? env.manage.gatewayUrl : env.local.gatewayUrl) || null,
-        sandbox: env.sandbox,
+        sandbox: sandboxEngine()?.name ?? "off",
         browser: env.browserCdpUrl ? "cdp" : "local",
         files: env.s3.bucket ? "s3" : "data folder",
         database: env.databaseUrl ? "libsql" : "file",

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

@@ -1,7 +1,7 @@
 ---
 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
+version: 0.7.3
 ---
 
 You extend engenty wizards with **plugins**. A plugin adds to a runtime without changing its
@@ -21,6 +21,11 @@ code, and the runtime loads it from its files while it runs.
 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`.
 
+## Wizards in other systems
+
+[Integration](./integration/index.md) shows how a published wizard reaches other systems: people
+over a link, a website or a channel, AI apps over MCP, and your own code.
+
 ## What you need
 
 - engenty wizards on your computer, or a checkout of

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

@@ -0,0 +1,11 @@
+---
+title: Channels
+description: Run a wizard as a chat, a conversation or a call, and over WhatsApp, SMS or the phone.
+version: 0.7.4
+---
+
+This page is not written yet.
+
+Until then, [Channels](../../user/test-and-share.md#channels) in the user guide describes how a
+wizard runs as a chat, a conversation or a call, and over WhatsApp, SMS or the phone. A plugin
+adds a channel of its own with a [runner](../plugins/runners.md).

package/apps/runtime/dist/docs/dev/integration/claude-code-plugin.md

@@ -0,0 +1,10 @@
+---
+title: Claude Code plugin
+description: Build and use wizards from Claude Code with the /wizard command and its skills.
+version: 0.7.4
+---
+
+This page is not written yet.
+
+Until then, [The Claude Code plugin](../../user/ai-apps.md#the-claude-code-plugin) in the user
+guide shows how you install it.

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

@@ -0,0 +1,10 @@
+---
+title: Embed
+description: Put a published wizard on your website with one script tag.
+version: 0.7.4
+---
+
+This page is not written yet.
+
+Until then, [Embed in a website](../../user/test-and-share.md#embed-in-a-website) in the user
+guide shows the script tag and its options.

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

@@ -21,6 +21,7 @@ version: 0.5.0
 | `wizards stop` | Stops it, with any other copy of it still running in the background. Your data is kept. AI apps that use your wizards start it again when you use one there |
 | `wizards restart` | Stops it and starts it again; after an update, that is the new version. If it isn’t running, it starts in the background |
 | `wizards update` | Installs the latest version |
+| `wizards sandbox add` / `remove` | Adds the sandbox where AI steps run code, or removes it. It is agentOS, about 340 MB, and needs no Docker. Without a sandbox, steps can’t run code. `wizards sandbox` alone shows whether it is there. Name an engine to add another one: `wizards sandbox add agentos` |
 | `wizards autostart on` / `off` | Starts it when you log in, or stops doing so. It is a LaunchAgent on macOS and a systemd user service on Linux |
 | `wizards connect [app …]` | Adds your wizards to your [AI apps](./ai-apps.md): every app found, or the ones you name |
 | `wizards disconnect [app …]` | Takes them out again |
@@ -51,6 +52,7 @@ running, `wizards start` opens the running one instead of starting a second.
 | `~/.engenty/wizards/.env` | The settings file |
 | `~/.engenty/wizards/plugins` | [Plugins](./plugins.md) on this computer |
 | `~/.engenty/wizards/logs` | Logs: `install.log`, `update.log`, `runtime.log` when it runs in the background, `autostart.log` when a Mac starts it at login |
+| `~/.engenty/wizards/engines` | The sandbox, once `wizards sandbox add` put it there: one folder per engine |
 | `~/.engenty/wizards/tools`, `runtime` | Its own Node.js, and engenty wizards itself |
 | `~/.engenty/wizards/bin/wizards` | The command; `~/.local/bin/wizards` links to it |
 
@@ -65,6 +67,7 @@ the studio doesn’t: one `NAME=value` per line. Restart engenty wizards after a
 | `API_PORT` | The port | `24368`; if it is taken, the next free one up to `24387` |
 | `CHROME_PATH` | The browser for PDF and PNG exports and steps on websites: Chrome, Edge, Chromium or Brave | The first one found: on a Mac Google Chrome, Microsoft Edge, Chromium or Brave in `/Applications` or `~/Applications`; on Linux `google-chrome`, `chromium`, `chromium-browser` or `microsoft-edge` on the PATH. `wizards status` names it |
 | `FFMPEG_PATH` | ffmpeg for MP4 videos | `ffmpeg` |
+| `SANDBOX_ALLOW_HOSTS` | Addresses the sandbox reaches besides the npm and PyPI registries, comma-separated: `api.example.com`. It reaches nothing else | not set |
 | `OLLAMA_URL` | Where Ollama answers | `http://127.0.0.1:11434/v1` |
 | `PLUGINS_DIR` | Folders with plugins, comma-separated. If you set it, it replaces the default | `~/.engenty/wizards/plugins` |
 | `PLUGINS_WATCH` | With `0`, plugins no longer load again when their files change | `1` |

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

@@ -35,7 +35,7 @@ The logs show a link (“Open the studio: …”). Open it once: it signs your b
 | Data | Databases and files are on the `/data` volume. Back that volume up |
 | Models | Your own API keys or Ollama. The subscriptions of AI clients live on your own computer, not on a server |
 | PDF, PNG, browser steps, MP4 | Chromium and ffmpeg are in the image |
-| Code & shell | The sandbox is off in this image, so steps can’t use that tool. `compose.yaml` shows how to switch it on |
+| Code & shell | The sandbox is off in this image, so steps can’t use that tool. `compose.yaml` shows how to switch it on: with Docker, or with agentOS built into the image |
 | Plugins | Put them in a folder that you mount into the container and name in `PLUGINS_DIR` |
 
 ## Update

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.