# Workflows

Steps run in order. Any `{{name}}` is replaced before the step runs, and can
reference an input or an earlier step.

```ts
import { workflow } from "@praecise/harness";

export default workflow({
  input: { message: "the customer's message" },
  steps: [
    { id: "sorted", ask: "{{message}}", agent: "triage" },
    {
      id: "reply",
      when: "{{sorted.category}}",
      is: {
        refund: [
          { id: "draft", ask: "Draft a refund reply: {{message}}", agent: "support" },
          { id: "approved", approve: "Send this?\n\n{{reply.draft}}" },
        ],
      },
      otherwise: [{ id: "draft", ask: "Reply to: {{message}}", agent: "support" }],
    },
  ],
});
```

Eight kinds of step:

| | |
|---|---|
| `ask` | delegate to an agent |
| `use` | call a service, e.g. `use: "ledger.create_invoice"` |
| `approve` | stop and wait for a human |
| `wait` | stop and wait for an event from outside |
| `each` | run steps once per item, optionally in parallel |
| `when` | branch on a value |
| `repeat` | run steps until a check holds, with a required `max` |
| `plan` | let a model lay out the remaining work, then run it as a graph |

An `approve` step writes the run to disk and returns. It survives a restart, and
resuming replays the recorded outputs rather than re-running the steps before
it — the model is not called twice for work already done.

A `wait` step stops the same way, for an event instead of a person:

```ts
{ id: "paid", wait: "com.acme.payment.received", subject: "{{order}}", timeout: 86400, onTimeout: "continue" }
```

`wait` is the CloudEvent `type` awaited. `source` and `subject` narrow it, which
is how a run waits for its own event and not the next one of that type. The
event that matches continues the run, once, and is the step's output: `type`,
`source`, `id`, `subject`, `time`, `data` and `timedOut`. It arrives through
`app.signal(event)`, `app.deliver(workflow, event)`, `app.publish(event)` or the
[event routes](#events). An event that arrives while nothing waits for it is not
kept. `timeout` is in seconds; running out fails the run, or with
`onTimeout: "continue"` carries on with `{ timedOut: true }`. A timeout fires
only while a process holds the app, or when `app.expire()` is called: nothing
wakes a run whose app is not running. A run waits for one event at a time.

A string that is *only* a reference keeps its type, so `with: "{{draft}}"` hands
a tool an object rather than `[object Object]`.

Any step may carry `after: ["id", ...]`. One `after` anywhere turns the list into a
graph: steps run as soon as what they wait for is done, so independent work goes in
parallel instead of in the order it happened to be written. Without any `after`, the
steps run in order, which is what a short workflow wants.

Two things about `after` that are easy to read the wrong way, because both are about
where a step SITS rather than what it says:

A step inside `each`, `when` or `repeat` may wait for a step outside it, and usually
means to. If the block it sits in already waits for that step, the dependency is
satisfied before the block begins — naming it again is redundant rather than wrong,
and nothing is lost. What is reported is the other case: a wait on something nobody
waits for, where the two really could run in either order.

A `repeat` condition may name the steps inside its own body. `until: "{{panel.passed}}"`
over a body containing `panel` is the ordinary way to write "go round again until the
panel agrees", and it works because the condition is evaluated after the body has run.

`max` is required on `repeat` because an unbounded loop is a bug, so there is no way
to write one. And a `plan` is produced once rather than on every step — deciding what
to do next is itself a model call, and paying for it repeatedly is what makes agentic
loops expensive. The plan is recorded as a version rather than overwritten, so a
resume runs the graph that was agreed rather than inventing a fresh one.
