@falai/agent 4.0.0-alpha.12 → 4.0.0-alpha.13

package/docs/concepts/collection.md

@@ -7,7 +7,7 @@ order: 4
 
 # Field collection
 
-A field is one piece of data the conversation collects: a name, a company, a budget, a yes or no. You declare each field once, on the agent, with how to ask for it. Steps say which fields they collect. The model asks and extracts. Code decides what is still missing.
+A field is one piece of data the conversation collects: a name, a company, a budget, a yes or no. You declare each field once, on the agent, with how to ask for it. A flow lists the fields it needs, and its steps say which to ask and when. The model asks and extracts. Code decides what is still missing.
 
 ## Declared once
 
@@ -41,12 +41,45 @@ type Data = DataOf<typeof f>;
 |---|---|
 | `type` | `'string'`, `'number'`, `'integer'` or `'boolean'`. Values are coerced to it on the way in. |
 | `enum` | The allowed values. A value outside the list is dropped. It becomes a literal union in `Data`. |
+| `label` | The name a person reads, in an editor or next to a collected value. The model never sees it. |
 | `description` | What the field means, for the model. |
 | `ask` | How the model should ask for it. A step may override it. |
 | `extract` | Where a value may come from: `'anywhere'` or `'asked'`. The default depends on `type`, below. |
 
 `f.fields()` binds the data type, so `collect`, `ask`, `clearOnStart`, `{ step, clear }`, `if: { equals }` and an action's `ctx.set()` are all checked against these field names at compile time. The collected values live in `session.data` as a `Partial<Data>`.
 
+## A flow's data, a step's questions
+
+A scheduling flow needs one set of fields and a triage flow another. The flow's `collect` lists the fields it needs. Each talk step's `collect` says which of them to ask now, in what order: one field, or several when the step's prompt asks them together.
+
+```ts
+import { falai } from "@falai/agent";
+
+const f = falai().fields({
+  nome: { type: "string", label: "Nome", ask: "Pergunte o nome." },
+  dia: { type: "string", label: "Dia", ask: "Pergunte qual dia fica melhor." },
+  orcamento: { type: "number", label: "Orçamento" },
+});
+
+const agenda = f.flow({
+  id: "agenda",
+  name: "Agendamento",
+  on: [{ message: ["quer agendar uma visita"] }],
+  collect: ["nome", "dia", "orcamento"],
+  steps: [
+    { id: "quem", collect: ["nome"], question: "Claro! Qual é o seu nome?" },
+    { id: "quando", prompt: "Ofereça terça ou quinta.", collect: ["dia"] },
+    { id: "fim", say: "Combinado, {{data.nome}}. Até {{data.dia}}." },
+  ],
+});
+
+export { agenda };
+```
+
+No step asks for `orcamento`. It is still on the flow's list, so when the customer mentions a budget while this flow holds the conversation, the value is noted. A field on the list that only an answer can fill (`extract: 'asked'`, every boolean by default) and that no step asks can never be filled; `validateFlow` warns about it.
+
+Step one asks with fixed text: `question`. Its first ask goes out word for word, with no model call. It goes out only when every field the step collects is still missing. If the customer's first message already gave the name, the step is skipped. A later ask is the model's own wording, so a customer who replies with a question gets an answer.
+
 ## Known and pending
 
 A field is **known** when its value is not `undefined`, `null` or `''`. Anything else is unknown. There is no "asked but refused" state, only a count.
@@ -69,7 +102,7 @@ Four writers reach `session.data`. Two are the model, two are your code.
 
 | Writer | Which fields | When |
 |---|---|---|
-| The understand call | Unknown fields with `extract: 'anywhere'` listed by any talk step of the floor's flow or of a candidate `message` flow | On a message, before runs move |
+| The understand call | Unknown fields with `extract: 'anywhere'` that the floor's flow or a candidate `message` flow lists, in its own `collect` or a talk step's. With nobody on the floor, also the catch-all's (`message: []`) | On a message, before runs move |
 | The speak call | The speaking step's pending fields, whatever their `extract`, in the envelope `{ message, ...fields }` | When the step speaks |
 | A tool's `data` | Whatever the tool returns | During a speak round, written as given |
 | An action's `ctx.set(patch)` | Whatever the action writes | During a `do` step, written as given |
@@ -110,7 +143,7 @@ This split also decides which call spends tokens on what. On a message, the unde
 { kind: 'collect', status: 'skipped', code: 'max-asks', detail: 'orcamento' }
 ```
 
-One line per field that ran out of asks, with the field's slug in `detail`. `maxAsks: 1` means "ask once, do not insist". The field stays unknown: a later step may still collect it, and a later run of the flow starts the count again, because `asked` lives on the run.
+One line per field that ran out of asks, with the field's slug in `detail`. `maxAsks: 1` means "ask once, do not insist". The field stays unknown: a later step may still collect it, and a later run of the flow starts the count again, because `asked` lives on the run. A step's fixed `question` counts as one ask. `{ step, clear }` resets the count of the fields it clears, so a confirmation loop asks from scratch each round.
 
 ## Known fields are never re-extracted
 
@@ -157,11 +190,13 @@ Three layers of text shape the question, from general to specific.
 2. The step's `ask: { orcamento: '…' }`: wins over the field's, for that step only.
 3. The step's `prompt`: the guideline for the whole reply. Without one, the default is "Collect what is still missing below, in the flow of the conversation, one or two things per message."
 
-All three are templates: `{{data.x}}`, `{{context.x}}` and `{{input.x}}` are filled in before the model reads them. The model sees every pending field of the step with its wording, in collect order, and is told to ask at the pace the prompt sets and to take any value the customer's message already answers.
+A step's `question` skips all three for the first ask: it is the exact text the customer reads. Every later ask goes back to the three layers.
+
+All four are templates: `{{data.x}}`, `{{context.x}}` and `{{input.x}}` are filled in before the model reads them. The model sees every pending field of the step with its wording, in collect order, and is told to ask at the pace the prompt sets and to take any value the customer's message already answers.
 
 ## What the provider sees
 
-`toWireSchema` in `src/utils/schema.ts` is the only way a field definition reaches a provider. It keeps `type`, `description` and `enum` and strips `ask`, `extract` and `optional`: those are for the framework, not the model. The result is a closed JSON schema (`additionalProperties: false`). In both envelopes every property is required and nullable, so the model must answer each field with a value or `null`. A field name that is not a legal property name for the provider, or is spelled `message`, travels under an alias and is mapped back on the way out.
+`toWireSchema` in `src/utils/schema.ts` is the only way a field definition reaches a provider. It keeps `type`, `description` and `enum` and strips `label`, `ask`, `extract` and `optional`: those are for the framework, not the model. The result is a closed JSON schema (`additionalProperties: false`). In both envelopes every property is required and nullable, so the model must answer each field with a value or `null`. A field name that is not a legal property name for the provider, or is spelled `message`, travels under an alias and is mapped back on the way out.
 
 ## Where next
 

package/docs/concepts/pipeline.md

@@ -62,7 +62,7 @@ Code first works out what there is to judge:
 - **Candidates**: the flow holding the floor, whatever its trigger, plus every `message` flow with a non-empty phrase list whose `if` holds and whose `repeat` allows a start, in flow order. `message: []` catch-alls are never scored.
 - **Mentions**: every `mention` flow with a non-empty list whose `repeat` allows a start.
 - **Branches**: the `when` branches of the asking step.
-- **Fields**: every unknown field with `extract: 'anywhere'` listed by any talk step of the floor's flow or of a candidate flow.
+- **Fields**: every unknown field with `extract: 'anywhere'` that the floor's flow or a candidate flow lists, in its own `collect` or a talk step's. With nobody on the floor, the catch-all that would take the message adds its fields too, because an opening message often says the most. The fields its first step asks are read by that step's own speak call, so on their own they are not worth a call. A first step with a fixed `question` has no speak call, so its fields do count.
 
 Then the shortcuts, each worth zero calls:
 
@@ -140,11 +140,12 @@ Every row but the last is asserted by a scenario in `tests/scenarios/`; the comp
 | Turn | Calls | Why | Scenario |
 |---|---|---|---|
 | A message with a floor holder, several candidate flows, or one candidate that a catch-all or the idle speaker could stand in for | 2 | understand, then speak | S1, S13 |
-| A message with nothing to judge: a catch-all alone, a floor holder alone, or one flow with `idle: 'silent'` and no catch-all | 1 | speak only | S0, S1, S8 |
+| A message with nothing to judge: a catch-all alone with nothing to learn beyond what its first step asks, a floor holder alone, or one flow with `idle: 'silent'` and no catch-all | 1 | speak only | S0, S1, S8, S14 |
 | A message with no flows, answered by the idle speaker | 1 | speak only | S9 |
 | A message where a mention flow's `say` answers | 1 | understand only; the floor's talk is skipped | S4 |
 | Each tool round | +1 | one more speak call | S8, S9 |
 | A wake or start that reaches a talk step | 1 | speak only; there is no message to understand | S2, S5, S12 |
+| A step's first ask with a fixed `question` | 0 | the text goes out as written | S14 |
 | A wake or start that runs only `do`, `wait` and `if` steps | 0 | code only | S5 (the start; its defer test covers the wake) |
 | Any input under `silenced` (a plain reason) | 0 | `do` steps run, nobody speaks; `{ reason, understand: true }` still spends the understand call | S2, S12 |
 | A message with `idle: 'silent'` and no eligible flow | 0 | nothing to judge, nobody speaks | S9 |

package/docs/reference/fields.md

@@ -21,6 +21,7 @@ interface ScalarDef<T extends ScalarType = ScalarType> {
 }
 
 interface FieldDef<T extends ScalarType = ScalarType> extends ScalarDef<T> {
+  label?: string;
   ask?: string;
   extract?: "anywhere" | "asked";
 }
@@ -37,6 +38,7 @@ type DataOf<T extends { fields: FieldDefs }> = InferData<T["fields"]>;
 |---|---|---|---|
 | `type` | `ScalarType` | required | `'string'`, `'number'`, `'integer'` or `'boolean'`. |
 | `enum` | `readonly (string \| number)[]` | none | The allowed values. A value outside the list is dropped (`code: 'not-in-enum'`). In the data type the field becomes the literal union. |
+| `label` | `string` | none | The name a person reads, in an editor or next to a collected value. Never sent to the model. |
 | `description` | `string` | none | What the field is. Sent to the model with the field's type and options. |
 | `ask` | `string` | none | How the model should ask for it. Sent to the speak call as "How to ask" while the field is pending. A talk step's own `ask` overrides it. A template: `{{data.x}}` and `{{context.x}}` are filled in. |
 | `extract` | `'anywhere' \| 'asked'` | `'anywhere'` for string, number and integer; `'asked'` for boolean | Where a value may be taken from. `'anywhere'`: any message from the customer, whether or not the field was asked. `'asked'`: only the reply to the step that lists the field, so a stray "sim" never confirms anything. |
@@ -55,7 +57,7 @@ Properties are readonly — `fields()` takes the definitions as a `const` type,
 
 **Known.** A field is known when its value is not `undefined`, `null` or `''`. Known fields are never asked again and never re-extracted; both calls list them under "Already known".
 
-**Which call extracts what.** The understand call, on a message turn, extracts every unknown `'anywhere'` field named in a `collect` of the flow holding the floor and of every eligible message flow, in one envelope. The speak call extracts the pending fields of the step that speaks, `'asked'` ones included, in the same call that phrases the reply. Tools write `data` and actions call `ctx.set()`; those values are written as given, with no check.
+**Which call extracts what.** The understand call, on a message turn, extracts every unknown `'anywhere'` field that the flow holding the floor or an eligible message flow lists, in the flow's own `collect` or a talk step's, in one envelope. With nobody on the floor, the catch-all's fields are read too. The speak call extracts the pending fields of the step that speaks, `'asked'` ones included, in the same call that phrases the reply. Tools write `data` and actions call `ctx.set()`; those values are written as given, with no check.
 
 **Coercion.** A raw value from the model goes through `coerceField(def, raw)` before it is written:
 
@@ -68,9 +70,9 @@ Properties are readonly — `fields()` takes the definitions as a `const` type,
 
 Anything else is dropped with the outcome line `code: 'bad-value'`. A value outside `enum` is dropped with `code: 'not-in-enum'`. A value for a slug that is not a field is dropped with `code: 'unknown-field'`. Dropped values leave a `collect` outcome with status `skipped` and no run id; the field stays pending and is asked again.
 
-**What reaches the provider.** `toWireSchema(defs)` turns definitions into the JSON schema the model must fill: a closed object (`additionalProperties: false`) with one property per field carrying `type`, `description` and `enum`, and nothing else. `ask` and `extract` are stripped; they steer the framework, not the schema. In the envelope style used by both calls every property is required and nullable (`type: [type, 'null']`), so the model answers `null` for what the customer did not give. The prompt describes each field once more in words (`nome (string) [a | b]: description`) and, in the speak call, adds the pending field's "How to ask".
+**What reaches the provider.** `toWireSchema(defs)` turns definitions into the JSON schema the model must fill: a closed object (`additionalProperties: false`) with one property per field carrying `type`, `description` and `enum`, and nothing else. `label`, `ask` and `extract` are stripped; they are for people and the framework, not the schema. In the envelope style used by both calls every property is required and nullable (`type: [type, 'null']`), so the model answers `null` for what the customer did not give. The prompt describes each field once more in words (`nome (string) [a | b]: description`) and, in the speak call, adds the pending field's "How to ask".
 
-**Clearing.** `{ step, clear: ['x'] }` on a `then`/`else`/branch and `clearOnStart` on a flow delete the field from `session.data`, so the next step that collects it asks again. `maxAsks` on a talk step (default 3) is the other way a field stops being pending: it is skipped for that run with `code: 'max-asks'`, the field in `detail`.
+**Clearing.** `{ step, clear: ['x'] }` on a `then`/`else`/branch and `clearOnStart` on a flow delete the field from `session.data`, so the next step that collects it asks again. `{ step, clear }` also resets how many times the run asked it. `maxAsks` on a talk step (default 3) is the other way a field stops being pending: it is skipped for that run with `code: 'max-asks'`, the field in `detail`.
 
 **Action parameters** use the sibling type `ParamDef`: a `ScalarDef` plus `optional?: true`, or `{ type: 'array', items: ScalarDef }`. `InferParams<P>` gives the `with` shape. They share `toWireSchema` and the same strictness at construction. See [Actions, events and conditions](actions-events-conditions.md).
 

package/docs/reference/flow-spec.md

@@ -23,6 +23,7 @@ interface FlowSpec {
   on?: TriggerSpec[];
   anchor?: string;
   while?: ConditionSpec;
+  collect?: string[];
   clearOnStart?: string[];
   steps: StepSpec[];
   onEnd?: "end" | "stay" | "reset";
@@ -33,7 +34,7 @@ interface FlowSpec {
 type StepSpec = StepBase &
   (
     | { kind: "prompt"; prompt: Template; ask?; maxAsks?; branches?: BranchSpec[]; tools?; instructions?: InstructionSpec[] }
-    | { kind: "collect"; collect: string[]; prompt?: Template; ask?; maxAsks?; branches?: BranchSpec[]; tools?; instructions?: InstructionSpec[] }
+    | { kind: "collect"; collect: string[]; prompt?: Template; question?: Template; ask?; maxAsks?; branches?: BranchSpec[]; tools?; instructions?: InstructionSpec[] }
     | { kind: "say"; say: Template; media?: { slug: string }; once?: boolean }
     | { kind: "do"; do: string; with?: Record<string, unknown>; onFail?: Next }
     | { kind: "wait"; wait: Duration; businessHours?: boolean; else?: Next; branches?: BranchSpec[] }
@@ -120,7 +121,7 @@ Every message has the form `[FlowConfigurationError] <where>: <what>. <fix>`, wh
 | Reserved step id | `uses the reserved id "end"` | "end" ends the run; pick another id. |
 | Duplicate step id | `duplicates an earlier step id` | Give each step its own id. |
 | Triggers, no steps | `has triggers but no steps` | Add at least one step or remove `on`. |
-| Unknown field | `unknown field "x" in collect` (also `ask`, `clearOnStart`, `then.clear`, `while.equals`, `if.known`, …) | Add it to the agent's fields or fix the slug. |
+| Unknown field | `unknown field "x" in collect` (the flow's or a step's; also `ask`, `clearOnStart`, `then.clear`, `while.equals`, `if.known`, …) | Add it to the agent's fields or fix the slug. |
 | Unknown tool | `unknown tool "x"` (flow or step `tools`) | Register it in the agent's tools or fix the name. |
 | Unknown action | `unknown action "x"` | Register it in actions or fix the name. |
 | Unknown event | `unknown event "x"` (trigger) or `unknown event "x" in wait` | Register it in events or fix the name. |
@@ -136,6 +137,7 @@ Every message has the form `[FlowConfigurationError] <where>: <what>. <fix>`, wh
 | Extra parameter | `action "notify" has no parameter "to"` | Remove it or fix the name. |
 | Branch without a test | `branches[0] has neither when nor if` | Give the branch an AI condition (when) or a code one (if). |
 | Backward `if` with no `else` | `"if" jumps back to "quem" with no else` | Add else so the false branch has somewhere to go. |
+| Fixed question, nothing to ask | `has a question but collects nothing` | A fixed question asks for fields: add collect, or send the text with a say step. |
 
 Parameter values are checked strictly: `"3"` is not a number, `3.5` is not an integer, and an `enum` must contain the value unless the string holds `{{`, because a template's value is only known at run time.
 
@@ -146,7 +148,8 @@ Two checks live in the agent constructor rather than in `validateFlow`: `flow "x
 | Warning | Why |
 |---|---|
 | `flow "f", step "s": then jumps back to "quem" without clear; the fields collected since stay known and those steps skip. Add clear: [...] to re-ask them.` | A `then`, `else`, `onFail` or branch target points at the same or an earlier step and clears nothing, so a collect step it lands on is skipped with `code: 'already-known'`. |
-| `flow "f", step "s": collects "nome", "empresa" with no prompt and no ask; the model has nothing to go on. Add a prompt or an ask per field.` | A collect step with no `prompt`, where no listed field has an `ask` on the step or on the agent. |
+| `flow "f", step "s": collects "nome", "empresa" with no prompt and no ask; the model has nothing to go on. Add a prompt or an ask per field.` | A collect step with no `prompt` and no `question`, where no listed field has an `ask` on the step or on the agent. |
+| `flow "f": collect lists "confirmado", which is only taken from the answer to a step that asks it, and no step does. Add it to a step's collect, or set extract: 'anywhere' on the field.` | A field in the flow's `collect` with `extract: 'asked'` (every boolean, by default) that no step's `collect` lists, so nothing can ever fill it. |
 
 ## flowSpecSchema
 

package/docs/reference/flow.md

@@ -19,6 +19,7 @@ interface Flow<C = unknown, D = unknown> {
   on?: Trigger<C, D>[];
   anchor?: string;
   while?: Pred<C, D>;
+  collect?: (keyof D & string)[];
   clearOnStart?: (keyof D & string)[];
   steps: Step<C, D>[];
   onEnd?: "end" | "stay" | "reset";
@@ -37,6 +38,7 @@ interface Flow<C = unknown, D = unknown> {
 | `on` | `Trigger<C, D>[]` | none | What starts a run. Absent or empty: only `turn({ start })` or another flow's `then: { flow }` starts it. See [Trigger](trigger.md). |
 | `anchor` | `string` | `'session'` | What a run is keyed to. `'session'` uses the session id. Any other name reads `input.anchors[name].key`, and falls back to the session id when the host did not pass that anchor. |
 | `while` | `Pred<C, D>` | the trigger's `if` | Re-checked before the run moves. When it stops holding, the run ends with `code: 'premise-changed'`. |
+| `collect` | `(keyof D & string)[]` | none | The data this flow needs, as agent field slugs. Talk steps' `collect` says which of it to ask, and in what order. |
 | `clearOnStart` | `(keyof D & string)[]` | none | Fields forgotten when a run of this flow starts, so a second run asks for them again. |
 | `steps` | `Step<C, D>[]` | required | In order. A run enters `steps[0]` and moves to the next step unless `then` says otherwise. See [Step](step.md). |
 | `onEnd` | `'end' \| 'stay' \| 'reset'` | `'end'` | What the run does after its last step. |
@@ -59,6 +61,8 @@ It enters `steps[0]` in the same turn unless the trigger has `after`. Keys and s
 
 **`while`.** Checked every time the run is about to move: at the start of each turn's run phase for a running run, and when an asking run resumes on a message. A parked run (`waiting`) or a suspended one is not checked until it moves again. Without `while`, the check is the trigger's `if`: the run holds while any trigger of the same kind as the one that started it would still fire. A run started by `start` or by another flow has no such trigger, so without `while` it always holds. A silence run also ends, with `code: 'customer-replied'`, when a wake finds that the customer wrote after the run started.
 
+**`collect`.** The flow's data is its `collect` plus every field its talk steps collect. While the flow holds the conversation, or could take it on this message, the understand call notes any of it the customer gives that is still unknown and has `extract: 'anywhere'`. A field no step asks is still noted that way; it is just never asked for. When nobody holds the conversation, the catch-all (`message: []`) that would take the message counts as a flow that could take it. See [Field collection](../concepts/collection.md).
+
 **`clearOnStart`.** Applied at start for every trigger kind, `start` and `{ flow }` chains included. Not applied when `onEnd: 'reset'` restarts the flow: reset keeps the data.
 
 **`onEnd`.**
@@ -77,7 +81,8 @@ It enters `steps[0]` in the same turn unless the trigger has `after`. Keys and s
 - no `id`, or `steps` is not a list
 - a step with no `id`, the id `'end'`, or an id used twice
 - triggers with zero steps
-- an unknown field slug in `clearOnStart`, `collect`, `ask`, `equals`, `known` or a `clear` list
+- an unknown field slug in the flow's `collect`, `clearOnStart`, a step's `collect`, `ask`, `equals`, `known` or a `clear` list
+- a `question` on a talk step that collects nothing
 - an unknown action in `do`; a `with` that misses a required parameter, names one the action does not have, or gives a value of the wrong type (`with` values are not coerced; a `{{template}}` string is accepted for any enum)
 - an unknown event in a trigger or in `wait: { event }`
 - an unknown condition name, or a malformed built-in (`equals` not an object, `known` not a list, `silenced` not a boolean); an `equals` value whose type does not match the field
@@ -87,7 +92,7 @@ It enters `steps[0]` in the same turn unless the trigger has `after`. Keys and s
 - a branch with neither `when` nor `if`
 - an `if` step whose `then` jumps backward with no `else`
 
-It returns warnings, logged by the agent, for two things that run but probably not as intended: a jump backward without `clear` (the fields collected since stay known, so those steps skip), and a `collect` step with no `prompt` and no `ask` on any of its fields.
+It returns warnings, logged by the agent, for three things that run but probably not as intended: a jump backward without `clear` (the fields collected since stay known, so those steps skip), a `collect` step with no `prompt`, no `question` and no `ask` on any of its fields, and a field in the flow's `collect` that only an answer can fill (`extract: 'asked'`) when no step asks it.
 
 `toSpec(flow)` throws `FlowConfigurationError` when a predicate is a function, because a function cannot be stored as JSON.
 

package/docs/reference/outcomes.md

@@ -25,7 +25,7 @@ type StepOutcomeCode =
   // A run ended early
   | "step-loop" | "step-gone" | "customer-replied" | "premise-changed" | "silenced"
   // A step
-  | "already-known" | "another-reply" | "already-sent" | "branch" | "max-asks"
+  | "already-known" | "asked-fixed" | "another-reply" | "already-sent" | "branch" | "max-asks"
   | "inline-delay" | "awaiting-trigger" | "awaiting-event" | "event-arrived"
   | "no-event" | "replied" | "no-reply"
   // A host action
@@ -134,6 +134,7 @@ Grouped by what produced it. `kind` and `status` are given as `kind / status`. A
 |---|---|---|---|
 | `prompt` or `collect / ok` | none; `llmCalls` set | The speak call answered. The run is asking if fields are still pending, else it moved. | none. This line never carries `next`, even when the run moves on; the lines that follow show where it went |
 | `collect / skipped` | `already-known` | The step was entered and every field it collects was already known (or at `maxAsks`). No call. | `then` |
+| `collect / ok` | `asked-fixed` | The step's `question` went out word for word as its first ask. No call; the run is asking. | |
 | `collect / ok` | none, no `llmCalls` | An asking step whose remaining fields were all known when the customer's next message resumed it: the understand call filled them in from the message, or an action's `ctx.set()` or a tool's `data` had written them since the step last asked. It moved without speaking. | `then` |
 | `collect / skipped` | `max-asks`, `detail` = the field slug | One line per field still unknown when the step moves on because that field reached `maxAsks` (default 3). | |
 | `prompt` or `collect / ok` | `branch` | A branch of the asking step fired: an `if` branch held, or the model answered `when` with true. | the branch's `then` |

package/docs/reference/step.md

@@ -44,6 +44,7 @@ The model speaks. A guideline, fields to collect, or both.
 ```ts fragment
 type TalkStep<C, D> = ({ prompt: Template; collect?: (keyof D & string)[] } | { collect: (keyof D & string)[]; prompt?: Template }) & {
   ask?: Partial<Record<keyof D & string, string>>;
+  question?: Template;
   maxAsks?: number;
   branches?: Branch<C, D>[];
   tools?: string[];
@@ -54,8 +55,9 @@ type TalkStep<C, D> = ({ prompt: Template; collect?: (keyof D & string)[] } | {
 | Field | Type | Default | Meaning |
 |---|---|---|---|
 | `prompt` | `Template` | "Collect what is still missing below, in the flow of the conversation, one or two things per message." | The guideline for the reply. Required when there is no `collect`. |
-| `collect` | `(keyof D & string)[]` | none | Fields to collect. The step is done when they are known. |
+| `collect` | `(keyof D & string)[]` | none | Fields to ask for now, in this order. The step is done when they are known. The flow's own `collect` lists everything it needs; see [Flow](flow.md). |
 | `ask` | `Partial<Record<slug, string>>` | the field's own `ask` | Per-flow wording for a field. |
+| `question` | `Template` | none | A fixed first question, sent word for word with no model call. Needs `collect`. |
 | `maxAsks` | `number` | `3` | Times a field may be asked before it is skipped (`code: 'max-asks'`, the field in `detail`). |
 | `branches` | `Branch<C, D>[]` | none | Exits judged while the step asks. See [Branches](branches.md). |
 | `tools` | `string[]` | the flow's `tools`, else all | Tools the model may call from this step. |
@@ -64,6 +66,7 @@ type TalkStep<C, D> = ({ prompt: Template; collect?: (keyof D & string)[] } | {
 - Pending fields are `collect` minus the known ones minus those at `maxAsks`, in `collect` order. A step the run enters whose pending list is empty is skipped with no model call (`code: 'already-known'`) and the run follows `then`. When the asking run resumes and the message filled the last field, the same move is logged `ok` with no detail.
 - Reaching a talk step suspends any other run that was asking; this run becomes the asker and holds the floor. It speaks in this turn if the speak call has not happened yet; otherwise it speaks on the next message.
 - The speak call returns the message plus one value per pending field. Values are validated and written; each field still pending is counted as asked once more. With pending fields left the run stays asking. With none left, or with no `collect` at all, the run follows `then` in the same turn.
+- With `question`, the step's first ask is that text, as a `kind: 'verbatim'` message with no speak call (`code: 'asked-fixed'`). It goes out only when every field in `collect` is still pending and none was asked yet, and never on a run that stays (`onEnd: 'stay'`). Reached after this turn's speak call, it goes out in the same turn, the way a `say` does. It counts as one ask of each field. Every later ask is the model's own wording, so a customer who asks something back gets an answer; `maxAsks` still applies. A `{ step, clear }` that clears the step's fields also clears their ask count, so the question goes out again.
 - With `silenced` set, a talk step ends the run with `code: 'silenced'` (`detail` = your reason); a run that was already asking stays asking instead.
 - Outcome kind: `collect` when `collect` is non-empty, else `prompt`.
 
@@ -154,7 +157,7 @@ The code forks. No model call.
 |---|---|
 | `'passo'` | Jump to that step id. |
 | `'end'` | Finish the run here, exactly as running past the last step does — `onEnd` still decides: `'end'` ends it, `'stay'` goes back to the last talk step and answers every message from there, `'reset'` starts a fresh run. `'end'` is reserved: no step may use it as an id. |
-| `{ step: 'passo', clear: ['campo'] }` | Delete the listed fields from `session.data`, then jump. The way to ask something again. |
+| `{ step: 'passo', clear: ['campo'] }` | Delete the listed fields from `session.data` and forget how many times the run asked them, then jump. The way to ask something again. |
 | `{ flow: 'outro', input? }` | End this run (reason `'flow'`) and start `outro` in the same turn, one hop deeper. The child gets `input`, or this run's `input` when absent. It holds the floor when this run did, or when no run did: a `mention` flow that chains does not take the message from the run it was routed to. `flow` is a template. |
 
 Entering a step counts a visit; the visit is part of every key minted there, so a step visited twice sends twice. A `{ step }` jump to an id that no longer exists ends the run with `code: 'step-gone'`; a `{ flow }` to an unknown flow is skipped with `code: 'flow-gone'`.

package/docs/rfc/v4-one-flow.md

@@ -104,6 +104,7 @@ type Trigger<C, D, Cond, E> = { repeat?: Repeat } & (      // default: message/m
 
 type Talk<C, D, Cond> = ({ prompt: Template; collect?: (keyof D)[] } | { collect: (keyof D)[]; prompt?: Template }) & {
   ask?: Partial<Record<keyof D, string>>;                   // per-flow wording; schema `ask` is the default
+  question?: Template;                                      // fixed first ask, verbatim, no call; needs collect
   maxAsks?: number; branches?: Branch<C, D, Cond>[]; tools?: string[]; instructions?: Instruction<C, D>[];
 };
 
@@ -121,6 +122,7 @@ interface Flow<C, D, Cond, A extends ActionMap, E> {
   on?: Trigger<C, D, Cond, E>[];        // absent or [] = Início manual
   anchor?: string;                      // 'session' (default) or a host anchor name — "vale por conversa / por lead"
   while?: Pred<C, D, Cond>;             // re-checked whenever the run moves; default = trigger `if`
+  collect?: (keyof D)[];                // the data this flow needs; steps' collect orders the asks
   clearOnStart?: (keyof D)[];
   steps: Step<C, D, Cond, A, E>[];      // ids required, unique, never 'end'
   onEnd?: 'end' | 'stay' | 'reset';     // default 'end'

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@falai/agent",
   "packageManager": "bun@1.4.2",
-  "version": "4.0.0-alpha.12",
+  "version": "4.0.0-alpha.13",
   "description": "Conversational state engine for TypeScript where the AI understands, but the code is in control",
   "type": "module",
   "main": "./dist/cjs/index.js",

package/src/core/FlowSpec.ts

@@ -44,7 +44,7 @@ import type {
 import type { StructuredSchema } from "../types/schema.js";
 import { isDuration } from "../utils/duration.js";
 import { splitPhrases } from "../utils/phrases.js";
-import { toWireSchema } from "../utils/schema.js";
+import { extractMode, toWireSchema } from "../utils/schema.js";
 
 // ── The JSON form ───────────────────────────────────────────────────────
 
@@ -77,7 +77,7 @@ interface TalkSpecExtras {
 export type StepSpec = StepBase<LooseData> &
   (
     | ({ kind: "prompt"; prompt: Template; collect?: undefined } & TalkSpecExtras)
-    | ({ kind: "collect"; collect: string[]; prompt?: Template } & TalkSpecExtras)
+    | ({ kind: "collect"; collect: string[]; prompt?: Template; question?: Template } & TalkSpecExtras)
     | ({ kind: "say" } & SayStep)
     | ({ kind: "do" } & DoStep<LooseData>)
     | { kind: "wait"; wait: Duration; businessHours?: boolean; else?: Next<LooseData>; branches?: BranchSpec[] }
@@ -92,6 +92,7 @@ export interface FlowSpec {
   on?: TriggerSpec[];
   anchor?: string;
   while?: ConditionSpec<LooseData>;
+  collect?: string[];
   clearOnStart?: string[];
   steps: StepSpec[];
   onEnd?: "end" | "stay" | "reset";
@@ -136,6 +137,7 @@ export function toSpec<C, D extends LooseData>(flow: Flow<C, D>): FlowSpec {
     on: flow.on?.map((trigger, i) => triggerToSpec(trigger, at(`trigger #${i + 1}`))),
     anchor: flow.anchor,
     while: jsonPred(flow.while, at("while")),
+    collect: flow.collect,
     clearOnStart: flow.clearOnStart,
     steps: flow.steps.map((step) => stepToSpec(step, at(`step "${step.id}"`))),
     onEnd: flow.onEnd,
@@ -189,11 +191,12 @@ function stepToSpec<C, D extends LooseData>(step: Step<C, D>, at: string): StepS
     instructions: step.instructions?.map((ins, i) => instructionToSpec(ins, `${at} instructions[${i}]`)),
   };
   if (step.collect !== undefined) {
-    return compact<StepSpec>({ ...base, kind: "collect", collect: step.collect, prompt: step.prompt, ...talk });
+    return compact<StepSpec>({ ...base, kind: "collect", collect: step.collect, prompt: step.prompt, question: step.question, ...talk });
   }
   if (step.prompt === undefined) {
     throw problem(at, "has neither prompt nor collect", "A talk step needs a guideline, fields to collect, or both.");
   }
+  if (step.question !== undefined) throw questionWithoutCollect(at);
   return compact<StepSpec>({ ...base, kind: "prompt", prompt: step.prompt, ...talk });
 }
 
@@ -248,6 +251,7 @@ interface LooseStep {
   onFail?: Next<LooseData>;
   prompt?: Template;
   collect?: string[];
+  question?: Template;
   ask?: Partial<Record<string, string>>;
   branches?: LooseBranch[];
   instructions?: LooseInstruction[];
@@ -262,6 +266,7 @@ interface LooseFlow {
   id: string;
   on?: LooseTrigger[];
   while?: LoosePred;
+  collect?: string[];
   clearOnStart?: string[];
   steps: LooseStep[];
   instructions?: LooseInstruction[];
@@ -421,7 +426,18 @@ export function validateFlow<C = unknown, D = LooseData>(
     }
   };
 
+  for (const field of flow.collect ?? []) slug(field, flowAt, "collect");
   for (const field of flow.clearOnStart ?? []) slug(field, flowAt, "clearOnStart");
+  // A field taken only from the answer to a step that asks it can never be filled when no step asks it.
+  const asked = new Set(flow.steps.flatMap((step) => step.collect ?? []));
+  for (const field of flow.collect ?? []) {
+    if (!asked.has(field) && extractMode(fields[field]) === "asked") {
+      warnings.push(
+        `${flowAt}: collect lists "${field}", which is only taken from the answer to a step that asks it, and no ` +
+          "step does. Add it to a step's collect, or set extract: 'anywhere' on the field.",
+      );
+    }
+  }
   pred(flow.while, flowAt, "while");
   toolNames(flow.tools, flowAt);
   flow.instructions?.forEach((ins, i) => pred(ins.if, flowAt, `instructions[${i}].if`));
@@ -483,8 +499,14 @@ export function validateFlow<C = unknown, D = LooseData>(
     if (step.collect !== undefined || step.prompt !== undefined) {
       for (const field of step.collect ?? []) slug(field, at, "collect");
       for (const field of Object.keys(step.ask ?? {})) slug(field, at, "ask");
+      if (step.question !== undefined && !step.collect?.length) throw questionWithoutCollect(at);
       const fields_ = step.collect ?? [];
-      if (step.prompt === undefined && fields_.length > 0 && fields_.every((f) => !step.ask?.[f] && !fields[f].ask)) {
+      if (
+        step.prompt === undefined &&
+        step.question === undefined &&
+        fields_.length > 0 &&
+        fields_.every((f) => !step.ask?.[f] && !fields[f].ask)
+      ) {
         warnings.push(
           `${at}: collects ${fields_.map((f) => `"${f}"`).join(", ")} with no prompt and no ask; the AI has nothing ` +
             "to go on. Add a prompt or an ask per field.",
@@ -655,6 +677,7 @@ export function flowSpecSchema(registries: Registries): StructuredSchema {
         kind: enumOf(["collect"]),
         collect: { ...slugList, description: "Fields the AI asks for until they are known" },
         prompt: orNull(STRING),
+        question: orNull({ type: "string", description: "A fixed first question, sent word for word; later asks are the AI's" }),
         maxAsks: orNull({ ...INTEGER, description: "Times a field may be asked before it is skipped; default 3" }),
         branches,
       }),
@@ -700,6 +723,7 @@ export function flowSpecSchema(registries: Registries): StructuredSchema {
     on: orNull(list(trigger, "What starts a run; null = started by hand")),
     anchor: orNull({ type: "string", description: "'session' (default) or a host anchor such as 'lead'" }),
     while: orNull({ ...condition, description: "The run ends when this stops holding" }),
+    collect: slugList && orNull({ ...slugList, description: "The data this flow needs; its steps ask for it in order, and any of it the lead gives is noted" }),
     clearOnStart: slugList && orNull({ ...slugList, description: "Fields to forget when a run starts" }),
     steps: list(step, "In order; a run moves to the next step unless `then` says otherwise"),
     onEnd: orNull(enumOf(["end", "stay", "reset"], "After the last step: end the run, stay on the last talk step it took answering every message, or reset to the first")),
@@ -751,6 +775,10 @@ function orNull(schema: StructuredSchema): StructuredSchema {
 
 // ── Shared helpers ──────────────────────────────────────────────────────
 
+function questionWithoutCollect(at: string): FlowConfigurationError {
+  return problem(at, "has a question but collects nothing", "A fixed question asks for fields: add collect, or send the text with a say step.");
+}
+
 function problem(at: string, what: string, fix: string): FlowConfigurationError {
   return new FlowConfigurationError(`[FlowConfigurationError] ${at}: ${what}. ${fix}`);
 }

package/src/core/Runner.ts

@@ -137,6 +137,13 @@ function talkKind(step: { collect?: readonly string[] }): StepOutcomeKind {
   return step.collect?.length ? "collect" : "prompt";
 }
 
+/** Everything a flow collects: its own `collect`, then each talk step's, once each. */
+function flowFields<C, D>(flow: Flow<C, D>): string[] {
+  const fields = new Set<string>(flow.collect);
+  for (const step of flow.steps) if (isTalk(step)) for (const field of step.collect ?? []) fields.add(field);
+  return [...fields];
+}
+
 function kindOf<C, D>(step: Step<C, D> | undefined): StepOutcomeKind {
   if (!step) return "if";
   if (isTalk(step)) return talkKind(step);
@@ -543,16 +550,25 @@ export class Runner<C = unknown, D = unknown> {
     }
     const fields: UnderstandRequest<C, D>["fields"] = {};
     const data: Record<string, unknown> = turn.session.data;
+    const harvestable = (field: string): boolean => {
+      const def = this.options.fields[field];
+      return def !== undefined && !isKnown(data[field]) && extractMode(def) === "anywhere";
+    };
     for (const flow of [...(floorFlow ? [floorFlow] : []), ...eligible]) {
-      for (const step of flow.steps) {
-        if (!isTalk(step)) continue;
-        for (const field of step.collect ?? []) {
-          const def = this.options.fields[field];
-          if (def && !isKnown(data[field]) && extractMode(def) === "anywhere") fields[field] = def;
-        }
-      }
+      for (const field of flowFields(flow).filter(harvestable)) fields[field] = this.options.fields[field];
+    }
+    const judging = messageFlows.length > 0 || mentionFlows.length > 0 || branches.length > 0 || Object.keys(fields).length > 0;
+    // With nobody on the floor the catch-all may take this message, and an opening message often says the most. The
+    // fields its first step asks ride on that step's speak call, so alone they spend no call; a fixed question has no speak call.
+    // ponytail: "first step" is steps[0]; a catch-all that opens with a say or an if pays the call for that step's fields too.
+    const fallback = floorRun ? undefined : this.messageFlows(turn, (list) => list.length === 0)[0];
+    if (fallback) {
+      const first = fallback.steps[0];
+      const free = new Set<string>(first && isTalk(first) && first.question === undefined ? first.collect : []);
+      const own = flowFields(fallback).filter(harvestable);
+      if (judging || own.some((field) => !free.has(field))) for (const field of own) fields[field] = this.options.fields[field];
     }
-    if (!messageFlows.length && !mentionFlows.length && !branches.length && !Object.keys(fields).length) return null;
+    if (!judging && !Object.keys(fields).length) return null;
     return {
       text: turn.what.text,
       history: this.historyOf(turn),
@@ -724,7 +740,31 @@ export class Runner<C = unknown, D = unknown> {
       turn.queue.push(resumed);
       await this.drain(turn);
     }
-    return this.speaker(turn);
+    const speaker = this.speaker(turn);
+    if (speaker && !("idle" in speaker) && this.askFixed(turn, speaker)) {
+      turn.talk = undefined;
+      return null;
+    }
+    return speaker;
+  }
+
+  /**
+   * Send the step's fixed question when this is its first ask: every field it collects still unknown, none asked yet,
+   * and the run not staying (a staying run answers the lead). The question counts as one ask of each field. False when
+   * the AI should phrase the ask instead.
+   */
+  private askFixed(turn: Turn<C, D>, { run, step, pending }: TalkRequest<C, D>): boolean {
+    const { question, collect = [] } = step;
+    if (question === undefined || run.staying) return false;
+    if (pending.length !== collect.length || pending.some((field) => (run.asked[field] ?? 0) > 0)) return false;
+    const key = this.stepKey(run, step);
+    turn.messages.push({ text: render(question, this.scope(turn, run)), kind: "verbatim", afterMs: turn.afterMs, key, runId: run.id, stepId: step.id });
+    turn.afterMs = 0;
+    turn.spokeBy.add(run.id);
+    turn.spoke = true;
+    for (const field of pending) run.asked[field] = (run.asked[field] ?? 0) + 1;
+    this.outcome(turn, run, { kind: "collect", status: "ok", key, code: "asked-fixed", stepId: step.id });
+    return true;
   }
 
   /**
@@ -873,7 +913,9 @@ export class Runner<C = unknown, D = unknown> {
         }
       }
       run.status = "asking";
+      // Reached after Speak (settle's drain), a talk step waits for the next message; a fixed question costs no call, so it goes out now, as a say would.
       if (!turn.speakDone) turn.talk = { run, flow, step, pending };
+      else this.askFixed(turn, { run, flow, step, pending });
       return;
     }
 
@@ -1014,7 +1056,11 @@ export class Runner<C = unknown, D = unknown> {
     }
     if ("step" in target) {
       const data: Record<string, unknown> = turn.session.data;
-      for (const field of target.clear ?? []) delete data[field];
+      // Forgetting a field means asking for it from scratch: its ask count goes too, so a fixed question goes out again.
+      for (const field of target.clear ?? []) {
+        delete data[field];
+        delete run.asked[field];
+      }
       this.jump(turn, run, flow, target.step);
       return;
     }

package/src/types/flow.ts

@@ -45,6 +45,8 @@ export interface ScalarDef<T extends ScalarType = ScalarType> {
 
 /** One collectable field, authored once on the agent. */
 export interface FieldDef<T extends ScalarType = ScalarType> extends ScalarDef<T> {
+  /** The name a person reads, in an editor or next to a collected value. The model never sees it. */
+  label?: string;
   /** How the AI should ask for this field when a step collects it. */
   ask?: string;
   /**
@@ -185,6 +187,12 @@ export type TalkStep<C = unknown, D = unknown> = (
 ) & {
   /** Per-flow wording for a field; the field's own `ask` is the default. */
   ask?: Partial<Record<keyof D & string, string>>;
+  /**
+   * A fixed first question, sent word for word with no model call when the step
+   * first asks: every field it collects is still unknown and none was asked yet.
+   * Any later ask is the AI's own wording. Needs `collect`.
+   */
+  question?: Template;
   /** Times a field may be asked before it is skipped. Default 3. */
   maxAsks?: number;
   branches?: Branch<C, D>[];
@@ -253,6 +261,12 @@ export interface Flow<C = unknown, D = unknown> {
   anchor?: string;
   /** Re-checked whenever the run moves. Default: the trigger's `if`. */
   while?: Pred<C, D>;
+  /**
+   * The data this flow needs, as agent field slugs. Its talk steps' `collect`
+   * says which of it to ask, and in what order; a field no step asks is still
+   * noted whenever the lead gives it while the flow holds the conversation.
+   */
+  collect?: (keyof D & string)[];
   clearOnStart?: (keyof D & string)[];
   steps: Step<C, D>[];
   /** What the run does after its last step. Default `'end'`. `'stay'`: the last talk step the run took answers every later message. */

package/src/types/session.ts

@@ -77,6 +77,7 @@ export type StepOutcomeCode =
   | "silenced"
   // A step
   | "already-known"
+  | "asked-fixed"
   | "another-reply"
   | "already-sent"
   | "branch"

package/src/utils/outcomes.ts

@@ -28,6 +28,7 @@ export const OUTCOME_MESSAGES = {
   silenced: "the host cannot speak right now",
 
   "already-known": "every field this step collects is known",
+  "asked-fixed": "the step's fixed question went out word for word",
   "another-reply": "another run already answered this turn",
   "already-sent": "this message was already sent once",
   branch: "a branch of this step fired",