@engenty/wizards-runtime 0.7.6 → 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/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/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.

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

@@ -1,6 +1,6 @@
 import { FORMATS, isLang, LANG_CODE, LANGS, LIST_FORMATS, TEXT_CLASSES, wizardLang, } from "@engenty-wizards/shared/definition";
 import { TableColumnValueError } from "@engenty-wizards/shared/engenty/data-tables";
-import { noteText } from "@engenty-wizards/shared/run";
+import { noteText, } from "@engenty-wizards/shared/run";
 import { machineTranslated, translateDefinition, } from "@engenty-wizards/shared/translation";
 import { getConnInfo } from "@hono/node-server/conninfo";
 import { and, eq } from "drizzle-orm";
@@ -220,6 +220,18 @@ async function publishedWizard(token) {
 function wantsTranslation(w, def, lang) {
     return w.translate && lang !== wizardLang(def);
 }
+/** What the wizard's pages ask, in order (`PublicWizard.fields`). */
+export function pageFields(def) {
+    return def.steps.flatMap((step) => step.type === "page"
+        ? step.fields.map((f) => ({
+            id: f.id,
+            label: f.label,
+            kind: f.kind,
+            ...(f.options?.length ? { options: f.options } : {}),
+            ...(f.required ? { required: true } : {}),
+        }))
+        : []);
+}
 /** What a wizard's page shows before a run: in the viewer's language where `as` is given. */
 async function publicBody(c, w, original, as) {
     const translated = as ? translateDefinition(original, as.memory) : null;
@@ -245,6 +257,7 @@ async function publicBody(c, w, original, as) {
                 machine: machineTranslated(as.memory, original),
             }
             : null,
+        fields: pageFields(def),
     };
 }
 export const publicRoutes = new Hono()

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

@@ -0,0 +1,133 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createCodeMode, createTool, noopObserve } from "@mastra/core/tools";
+import { QuickJsCodeModeTransport } from "@mastra/quickjs";
+import { clip } from "./shared.js";
+/**
+ * Code Mode: the model writes one TypeScript program that calls the step's tools as
+ * `external_*` functions — loops, `Promise.all`, filtering and sums — and only what the program
+ * returns goes back to the model.
+ *
+ * The program runs in QuickJS compiled to WebAssembly, inside the server process. It has no
+ * files, network, timers or modules: its only way out are the step's own tools, which run on
+ * the server exactly as when the model calls them. Every run gets a fresh runtime with its own
+ * heap. The limits below keep one program from tying up the server or a site it calls.
+ */
+export const CODE_LIMITS = {
+    /** Wall time of one program, its tool calls included. */
+    timeoutMs: 120_000,
+    /** Tool calls one program may make. */
+    maxCalls: 100,
+    /** Tool calls of one program running at the same time. */
+    maxParallel: 4,
+    /** Characters of the program's answer the model reads. */
+    resultChars: 20_000,
+    /** Characters of `console.log` output the model reads. */
+    logChars: 4000,
+};
+/** The id of the tool, the way the model calls it. */
+export const CODE_TOOL_ID = "execute_typescript";
+const program = new AsyncLocalStorage();
+/**
+ * Whether a tool is running for a program. Nobody can be asked from inside one: a tool that needs
+ * the person's yes refuses there and tells the model to call it directly.
+ */
+export function inProgram() {
+    return program.getStore() === true;
+}
+/** Heap of one program's QuickJS runtime. */
+const MEMORY_LIMIT_MB = 64;
+/** One transport for the process; it loads the WebAssembly module once, on the first program. */
+let transport = null;
+function quickJs() {
+    transport ??= new QuickJsCodeModeTransport({ memoryLimitMb: MEMORY_LIMIT_MB });
+    return transport;
+}
+/** Runs at most `max` tasks at a time; the others wait their turn. */
+function limiter(max) {
+    let running = 0;
+    const waiting = [];
+    return async (task) => {
+        if (running >= max) {
+            await new Promise((resolve) => waiting.push(resolve));
+        }
+        running++;
+        try {
+            return await task();
+        }
+        finally {
+            running--;
+            waiting.shift()?.();
+        }
+    };
+}
+/** What a program may call: tools the server runs itself (a provider's own search has no `execute`). */
+function callable(tools) {
+    return Object.fromEntries(Object.entries(tools).filter(([, tool]) => typeof tool?.execute === "function"));
+}
+/**
+ * Wraps each tool for one program run: the call count and the calls in flight are capped, and the
+ * tool knows it runs for a program (`inProgram`).
+ */
+function guarded(tools, ctx, limits) {
+    let calls = 0;
+    const slot = limiter(limits.maxParallel);
+    return Object.fromEntries(Object.entries(tools).map(([key, tool]) => [
+        key,
+        {
+            ...tool,
+            execute: (input, options) => {
+                calls++;
+                if (calls > limits.maxCalls) {
+                    throw new Error(`A program makes at most ${limits.maxCalls} tool calls. Split the work.`);
+                }
+                if (ctx.signal.aborted) {
+                    throw new Error("The run was stopped.");
+                }
+                return slot(() => program.run(true, () => tool.execute(input, options)));
+            },
+        },
+    ]));
+}
+/**
+ * The `execute_typescript` tool over `tools`, and the instructions that tell the model how to
+ * write a program. Null when there is nothing a program could call.
+ */
+export function codeTool(tools, ctx, limits = CODE_LIMITS) {
+    const reachable = callable(tools);
+    if (!Object.keys(reachable).length) {
+        return null;
+    }
+    const config = { id: CODE_TOOL_ID, tools: reachable, timeout: limits.timeoutMs };
+    // The instructions list the tools once; every program runs over fresh guards.
+    const { tool: base, instructions } = createCodeMode(config, quickJs());
+    const tool = createTool({
+        id: CODE_TOOL_ID,
+        description: "Run a TypeScript program that calls your tools as external_* functions: loops, Promise.all, filtering, sums. Only what it returns comes back to you. Use it when a task needs many tool calls or arithmetic over their results.",
+        inputSchema: base.inputSchema,
+        execute: async (input, options) => {
+            await ctx.emit("tool", { code: "runsProgram" });
+            const run = createCodeMode({ ...config, tools: guarded(reachable, ctx, limits) }, quickJs()).tool;
+            // Spans need a run being traced; a call without one still runs.
+            const result = (await run.execute?.(input, {
+                ...options,
+                observe: options?.observe ?? noopObserve,
+            }));
+            const logs = result.logs?.length ? clip(result.logs.join("\n"), limits.logChars) : "";
+            if (!result.success) {
+                return { success: false, error: result.error, ...(logs ? { logs } : {}) };
+            }
+            const answer = typeof result.result === "string"
+                ? result.result
+                : (JSON.stringify(result.result ?? null) ?? "null");
+            return {
+                success: true,
+                result: answer.length > limits.resultChars ? clip(answer, limits.resultChars) : result.result,
+                ...(logs ? { logs } : {}),
+            };
+        },
+    });
+    return {
+        tool,
+        instructions: `${instructions}\n\nA program makes at most ${limits.maxCalls} tool calls, ${limits.maxParallel} at a time, and stops after ${limits.timeoutMs / 1000} seconds. Return only what you need: a long answer is cut at ${limits.resultChars} characters. A tool that asks the person first cannot run from a program: call it directly.`,
+    };
+}

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

@@ -2,6 +2,7 @@ import { createTool } from "@mastra/core/tools";
 import { z } from "zod";
 import { refreshConnector, resolveConnector } from "../connectors/external.js";
 import { connectionContext } from "../connectors/index.js";
+import { inProgram } from "./code.js";
 import { attempt, clip } from "./shared.js";
 import { resolveFile } from "./store.js";
 const FILE_NOTE = " File content never passes through you: returned content is kept as a file and you get its path; to send a kept file, give `file:<path>` where an input asks for `*_base64`.";
@@ -116,6 +117,11 @@ async function toolsOf(connection, ctx, files) {
         }
         const key = `${connection.id}:${action.id}`;
         if (asks(connection, action) && !ctx.resources.allowed.has(key)) {
+            if (inProgram()) {
+                return {
+                    error: "This change waits for the person's yes, which a program cannot ask for. Call the tool directly, outside the program.",
+                };
+            }
             const answer = await ctx.ask({
                 kind: "confirm",
                 reason: action.summary || action.id,

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

@@ -12,6 +12,7 @@ import { sandboxCapabilities, shellToolDescription } from "../sandbox/index.js";
 import { snapshotFile } from "../services/files.js";
 import { hasStoreFiles } from "../store/index.js";
 import { browserTools } from "./browser.js";
+import { codeTool } from "./code.js";
 import { connectorTools } from "./connector.js";
 import { mailTools } from "./mail.js";
 import { assertPublicUrl, safeFetch } from "./net-guard.js";
@@ -143,9 +144,9 @@ export async function buildStepTools(step, ctx, resolved, uploads) {
         });
     }
     const files = new FileKeeper(ctx, assets);
-    if (allowed.has("browser")) {
-        Object.assign(tools, await browserTools(ctx, assets, files));
-    }
+    // The browser is one page, worked step by step, and it asks the person to sign in.
+    const browser = allowed.has("browser") ? await browserTools(ctx, assets, files) : {};
+    Object.assign(tools, browser);
     // The wizard's lists and files, the documents the person gave and the project's documents are
     // always at hand. An installed client gets tools over an MCP bridge its CLI starts for every
     // call, seconds of its own: a step with no use for the store goes without its tools, and
@@ -281,9 +282,19 @@ export async function buildStepTools(step, ctx, resolved, uploads) {
             });
         }
     }
+    // An installed client writes and runs code of its own.
+    let instructions;
+    if (allowed.has("code") && !isHarnessVendor(resolved.vendor)) {
+        const code = codeTool(Object.fromEntries(Object.entries(tools).filter(([key]) => !(key in browser))), ctx);
+        if (code) {
+            tools[code.tool.id] = code.tool;
+            instructions = code.instructions;
+        }
+    }
     return {
         tools,
         assets,
+        instructions,
         close: async () => {
             await mcp?.disconnect().catch(() => undefined);
         },