Human steps

A step where the run stops and waits for you: it shows what the agents prepared, asks you to choose or fill something in, and carries on down the path of the button you click.

A human step is a place in your workflow where the run stops and waits for you. The agents before it do their work and hand it over. You look at what they made, choose or fill something in, and click a button. The button you click decides which step runs next, and your answer goes to the agents after it.

Use one when a person should decide before the work goes on: pick the leads worth contacting, correct a draft, approve one of three options, or add a number only you know.

A human step is not an agent. It uses no model, no tools and costs nothing while it waits.

Add one

There are two ways.

Ask the chat builder. For example: "After the research step, add a step where I pick which leads to contact. Give it the buttons Send and Skip." The builder adds the step, writes its question, its fields and its buttons, and connects it.
Do it by hand. Open Manual controls at the top of the canvas and choose Add Human step. A card marked YOUR INPUT appears in a wave. Open it to set its name, what it asks, what you fill in, and its buttons.

A step has:

A name and a question, shown to you when the run gets there.
Fields (up to 20), if you need to fill something in. A field can be short text, long text, a number, a choice from a list, yes or no, or a date. Mark a field Required and the step will not send until you answer it.
Buttons (1 to 6). Each button is a possible answer.

Make the buttons lead somewhere

Draw connections from the human step to the steps that should follow it, as you would for any other step. Open a connection and, under Follow this button, choose which button makes it run. A connection set to Whatever is clicked runs whatever you click. A connection that follows another button is skipped, and the card of a step on a path you did not take reads Path not taken.

When Cerevisor draws a connection for you, from a human step to the step in the next wave, that connection follows the step's first button. With the buttons a new step starts with, the next step runs when you click Continue and not when you click Stop here. Open the connection to choose another button, or Whatever is clicked. If a connection you drew yourself follows no button, the next step runs whatever you click, and the connection shows no button name. The chat builder is told about such a connection; the check before a run does not show it to you.

Once a connection you set up follows a button, you cannot remove that button until you disconnect the connection. This stops a path from quietly going dead.

A human step cannot also be a decision step, and a wave that holds a human step cannot hold a decision step. A human step has no tools, skills, secrets or files of its own: you answer it, and the agents around it do the work.

What you see when the run gets there

The run stops at the step and Cerevisor opens a panel called Your input. It shows the question, what the agents before the step handed over, the fields and the buttons. Fill it in and click a button. The run goes on.

Close for now closes the panel, and the run keeps waiting. The footer reads Your input is needed (or 2 steps need your input). Click it to open the panel again.
Before a run starts, the start summary says which steps will stop and wait for you.
A waiting step shows a steady amber dot and the words Waiting for you. Afterwards the card reads You chose and the button's name.

There is no time limit. A step waits as long as it takes.

When several steps wait

When more than one step is waiting, from one run or from several workflows, each has a tab at the top of the panel, the oldest first. A tab shows the step, its workflow and when it started waiting. Click a tab, or use the arrow keys, to move between them. What you typed in one tab stays there while you look at another.

The panel opens on the step you asked for. Click Open on a waiting card on the canvas and you see that step. Click a desktop notification and you see the step it named. The footer opens on the oldest.
When you answer a step, its tab goes and the next tab opens.

If you prefer to see the steps of one run next to each other, open Settings, Admin and turn on Show human steps side by side. This is one switch for the whole app, not per workflow.

The page

By default a step shows a plain form: your question, the fields and the buttons. That is always enough to answer it.

A step can also have a page: a small web page made for this workflow that shows the data the way you need it. A table of leads you can tick, two drafts side by side, a form that fits your own words. It opens inside Cerevisor, never in your web browser, and it never leaves the app.

Where it is saved. In your workflow's folder, in a sub-folder called pages, as an .html file. It is saved once and reused every time the step runs. The workflow needs a saved folder first. If it has none, the chat builder asks you to save it.
How to make or change it. Ask the chat builder. For example: "Make a page for this step that shows the leads as a table." Or later: "Make the page show the price column first." Nothing else changes a page.
Switching. While the step waits you can choose Use the plain form or Use the page at any moment.

Why a changed page shows the plain form first

A page is only shown if it is exactly the page the chat builder wrote, or the page you last approved. A page the chat builder writes is used straight away: you are not asked to review it first. You can look at it with sample data at any time from the step's editor, with Review page. If the file changes in any other way (you edited it, a sync tool changed it, someone sent you a copy) Cerevisor does not show it. It shows the plain form and says This page changed since you last looked at it.

Click Review page. You see the page with sample data, and clicking its buttons there sends nothing. If you are happy with it, click Use this page. From then on it is shown again.

The same plain form is shown, with a sentence saying why, when the step has no page yet, the file is missing, it is larger than 512 KB, it cannot be read, or it sits outside the workflow's folder. It is also shown when the page's script has a mistake that stops it from running, since the page would show up empty: ask the chat builder to write the page again. The chat builder cannot save a page like that in the first place; it is told what is wrong and writes it again. A page that stops working while it is shown is replaced by the plain form too, and the review window will not let you use it.

What a page can and cannot do

A page runs in a locked frame. It cannot reach the rest of the app, your files, the internet or other windows. It cannot send an answer on its own: an answer only counts within a few seconds of a click or key press of yours inside the page. The page's own code decides what it sends in that moment, so a page is only as trustworthy as whoever wrote it: the chat builder, or you. It can only receive the data of that one run and send back one answer.

The data a page shows is what the agents before the step handed over: their replies, and up to 8 of the files they wrote in this run.

Cerevisor checks what the page sends before it accepts it: the button must be one of the step's buttons, required fields must be filled, and each field must match its kind. If something is wrong, you see why and nothing is sent.

Scheduled and hands-free runs

A human step waits in every kind of run, including a scheduled run and a run in Hands-free mode. It does not time out and it does not guess an answer.

When a step starts waiting while Cerevisor is behind other windows or the run is in the background, you get a desktop notification, Your input is needed. Click it and Cerevisor comes to the front with the panel open on that step. If the run was started without a window, the click brings the full app up.
The footer also counts the steps waiting for you, and so do the run window's waiting for you count, the world's tab in the dock and the dots beside Select and Pan, where a waiting step is a still amber dot.
The Operator does not run a workflow that holds a human step. It says The Operator does not run workflows that wait for you. Run this one yourself. A run of yours that is waiting at a human step does not hold the Operator up.
A repeating (cron) schedule does not start a second run of a workflow while an earlier run of it is still waiting at a human step. That start is skipped and a line in the console says so. The next start is armed as usual. A schedule that runs once, and a schedule that watches a folder for a file, still start: the new run waits at the step too.
The unattended software factory leaves human steps out, as it leaves out any step that needs a person.

Your phone

If you use the mobile companion, your phone gets a notification, Your input is needed, when a step starts waiting. Tapping it opens the run on the phone. It is a nudge only: the page and your answer stay on your computer. The notification arrives while the companion app is open on the phone (in the foreground). You need the current version of the companion app.

If Cerevisor closes while a step waits

The run is not lost, and it is not answered for you. It shows as interrupted. Open it and click Continue this run (see Continue a run). Cerevisor skips the work already done and the human step asks you again.

Limits to know

A human step runs only as part of the whole workflow. Using Run on the step alone, or running the workflow as a Power for another workflow, is refused with a sentence saying so.
A free canvas does not run as a whole, so it cannot hold a human step. Switch the workflow back to waves to add one.
An agent cannot review a person's answer, and cannot ask the step a question. If an agent asks a step that has already been answered, it gets the answer back as it was recorded.
Loop and Enhance, Endless mode, Progressive mode and the Operator never create, change or remove a human step or its page. Only the chat builder and you on the canvas do.
An answer's extra data from a page is limited to 256 KB. A text field holds up to 10,000 characters and a long text field up to 50,000.
Content from the web, or from an app's data connected straight to the step, keeps its warning. The step passes on the same caution as the agents before it, and your own typed answer does not make it cleaner.

For people who write their own pages

You normally do not write a page; the chat builder does. If you want to write or edit one yourself, this is the contract. It is the same text the chat builder is given. Remember that a page you edit must be reviewed again (Review page, then Use this page) before it is shown.

A human step's page is one self-contained HTML file. Cerevisor shows it inside the app, in a locked frame, when a run reaches the step.

What the page can use:
- cerevisor.onData(function (data) { ... }) gives the run's data: data.step (name, prompt, fields, buttons), data.inputs (a list of { from, text } from the connected agents), data.files (a list of { name, path, text }), and data.run (workflowName, sample, theme: "light" or "dark"). Call it once; it may be called again with fresh data.
- cerevisor.submit(buttonId, fields, details) sends the answer. buttonId is one of data.step.buttons[i].id. fields is an object keyed by the ids in data.step.fields, with strings, numbers, true or false. details is optional extra JSON (at most 256 KB), for example the rows the person edited.
- cerevisor.markdown(text) returns an element with the Markdown laid out: headings, lists, tables, code, quotes, bold and italic. It is built from text only, so it is safe for any text in data. Add it with appendChild.

Markdown: the text in data.inputs, and in data.files whose name ends in .md, is Markdown. Always show it with cerevisor.markdown, never as raw text and never with a parser of your own. To show one part of a file (a section, for example), pass that part's text. Put the element in a container with normal white-space and the page's body font, not white-space: pre or a monospace font.

Rules the page must follow, or it will not work:
- Everything inline: no external scripts, styles, fonts or images, and no network calls. Images may be data: URLs.
- Attach handlers with addEventListener inside a <script> element. Inline handlers such as are blocked.
- Do not use <form> submission, alert, confirm, prompt, window.open or links that leave the page.
- Show Markdown with cerevisor.markdown and every other text from data as text (textContent), never as HTML (innerHTML).
- Show one clear button per item of data.step.buttons, with its label, and call cerevisor.submit when it is clicked.
- Mark the fields declared in data.step.fields that are required, and keep the person's values when data arrives again.
- Follow data.run.theme for light or dark colours. Keep the layout calm and readable: a white or dark surface, one accent colour, no decoration.
- When data.run.sample is true the page is a preview with sample data.

A few more things that help when you write a page by hand:

A page can use inline styles and a <style> element. Scripts only run if they are written in the page file itself.
Text that comes from the run's data can contain anything an agent wrote or read on the web. Show it with textContent, or with cerevisor.markdown when it is Markdown: that keeps any HTML inside it as plain text, shows a link's words without following it, and loads an image only from a data: URL. If a page puts that text in as HTML, it can restyle the page and hide or relabel what you see, so check the page's buttons before you click.
Your answer arrives as a JSON record with the button, the fields and your extra data. The agents after the step read it as text, and a connection that follows a button runs on the button's id.
If a page replaces its own document or sends the frame somewhere else, Cerevisor stops showing it and falls back to the plain form.
A page written before cerevisor.markdown existed may show a report as raw text, with rows of | and ** marks. Ask the chat builder to write the page again and it will lay the Markdown out. The plain form always lays it out.