Runners

A runner is a way to run a wizard. The runtime has four: the stepped page at /w/<token>, the chat at /w/<token>/chat, live voice at /w/<token>/talk and the video call at /w/<token>/video. The last two are there only where a speech model is set up. A plugin adds more. The owner picks them per wizard when it is made, and later under “Change” in the share dialog. The link opens the first page runner that is on; the others answer under their own address or from their own channel.

Register a runner

server.registerRunner({
  id: "kiosk",
  label: { de: "Kiosk", en: "Kiosk" },
  kind: "page",
  capabilities: {
    input: ["text", "select", "multiselect", "toggle", "number", "date"],
    output: { shows: ["text", "image"], pictures: ["dashboard", "widget"] },
    asks: ["confirm"],
    review: ["accept", "regenerate"],
    waits: true,
    handoff: ["screen"],
  },
  page: ({ wizard, path, query }) => new Response(renderKiosk(wizard, path, query)),
});

A page runner is served at /w/<token>/<id> for every wizard that switched it on. When you run from source, where Vite serves the pages, the same handler answers at /api/public/wizards/<token>/runners/<id>; the public wizard’s runners list carries the right address either way.

Capabilities

The runner declares what it can do. The runtime works out per wizard how far it gets: everything in the channel, a hand-off to the run page at some steps, or not possible. Where it is not possible, the share dialog’s row says “Not possible:” with the steps. A kind the runtime does not know throws when the runner is registered.

Drive a run

server.runs holds the functions behind the MCP tools, for the plugin’s own door. A run started here is a live run of the published wizard for a person of that door.

server.registerPublicRoute({
  method: "POST",
  path: "/call/:token",
  handler: async ({ params, json }) => {
    const { from, said } = await json<{ from: string; said: string }>();
    const { runId, ticket, refused } = await server.runs.start({
      token: params.token,
      person: { channel: "phone", id: from },
      answers: { name: said },
    });
    const report = await server.runs.report(runId, { waitSeconds: 20 });
    if (report.waitingFor && "page" in report.waitingFor) {
      // Ask the next field; fields with inChat=false need the run page.
      const link = await server.runs.handoffUrl(runId);
    }
    return { runId, ticket, refused, report };
  },
});

A refused command throws an error with a status and a code (not_found, invalid, refused, no_credits); an invalid one also carries the fields that did not fit as data.fields. A route that lets it through answers that status with { error, code }.

What the person sees

• The wizard’s first page offers the runners that are on beside “Let’s go”.
• A hand-off is a link to the same run; nothing is asked twice. The run page knows the door’s person through the run, and “What this wizard remembers” is theirs there too.
• The space’s results carry the door a run came through.

The runner’s part of the share dialog

The row of a channel runner, with its number, keyword, link and QR code, comes from its address. What the owner changes per wizard, such as the keyword, the studio half registers as a section, and the share dialog draws it under its gear while the runner is on and set up:

studio.registerShareSection({ runner: "whatsapp", component: ShareSection });

function ShareSection({ wizard }: StudioShareSectionProps) {
  // wizard: { id, title }; the plugin's own routes hold the rest.
}

One section per runner. After a change, invalidating the query ["wizard-runners", wizard.id] redraws the row. The settings a channel needs once per tenant (the number, the token) go into a settings section.

Setting up inside the dialog

“Set up” in a row opens the plugin’s settings section, unless the studio half registers a setup. That setup opens inside the dialog instead, as a view with a back arrow, at the dialog’s height:

studio.registerShareSetup({
  runner: "sms",
  title: () => t("setupTitle"),
  component: Setup,
  notice: Notice,
});

function Setup({ wizard, Actions, done }: StudioShareSetupProps) {
  return (
    <>
      <p>…</p>
      <Actions>
        <Button onClick={() => ask.mutate()}>{t("request")}</Button>
      </Actions>
    </>
  );
  // done({ title: t("requested"), text: "…", tone: "waiting" }) goes back.
}

One setup per runner. A setup that asks the server for something calls the plugin’s own routes; the rows show what problem answers after done.

A thread door from the SDK

A messenger runs a wizard one message at a time: a field per question, options to tap or to number, a link to the screen for what the thread cannot take, the result as pictures and links. That conversation is the same on every messenger; the SDK holds it, and a plugin brings the surface: how a question is drawn there, how a file is fetched.

import { ThreadDoor, type ThreadSurface } from "@engenty/wizards/plugin/thread";

const surface: ThreadSurface = {
  runner: "sms",
  asks: ["text", "number", "select", "multiselect", "toggle", "date", "email", "url", "location"],
  async send(thread, prompt) {
    // prompt.kind: "text" | "choice" | "location" | "link" | "media": draw it as the channel allows.
    await twilio.send(thread.id, toText(prompt, thread.state.lang));
  },
};

const door = new ThreadDoor({ runs: server.runs, surface, offered, watch, unwatch, log });
// A webhook: door.inbound(thread, message). A run that changed: door.resume(thread).

Once a wizard runs, the door speaks the wizard’s language. Before that, it speaks the language all offered wizards share; when they differ, it keeps the language it spoke last, which is English in a new thread.

A messenger plugin is a surface of this door: the webhook on a public route, the keyword table, the number and the keyword in the share dialog are the plugin’s; buttons and lists, or numbered lines and links, are its surface.

A call

A call has no thread and no screen: the person talks with a realtime speech model, and the model fills the run through tools, as the chat’s live voice does in the browser. The runtime hands a plugin the tenant’s speech model for it:

const { apiKey, model } = await server.speech.conversation();
// Throws with the status 503 and the code `no_model` while no OpenAI key is set under Models.

A call plugin keeps the audio out of the runtime: the telephony provider hands the call to the speech model’s SIP endpoint with a token in a header, the model’s provider posts the incoming call to the plugin’s public route, and the plugin accepts it with the wizard’s rules and tools and answers the model’s tool calls over a WebSocket, driving the run with server.runs. What a voice cannot take goes out as a link.

Not there yet

• An event when a wizard is published, for a runner that prepares something per wizard.