@falai/agent 3.4.5 → 4.0.0-alpha.2

package/docs/reference/actions-events-conditions.md

@@ -0,0 +1,396 @@
+---
+title: "Actions, events, conditions"
+description: "The three host registries a flow names by string: actions a do step runs, events the host reports, conditions a JSON predicate can call."
+type: reference
+order: 7
+---
+
+# Actions, events, conditions
+
+You write these three in your code, and a flow names them with a string. An **action** does something when a `do` step reaches it: send an email, add a tag. An **event** is something that happened in your system. You report it with `turn({ event })`, and triggers and `wait` steps react. A **condition** is a yes/no check your code answers, so a flow stored as JSON can ask something the built-in tests cannot. Register all three on the agent, under `actions`, `events` and `conditions`. Every name a flow uses is checked when the agent is built.
+
+Source: `src/types/flow.ts`, `src/core/Runner.ts`, `src/core/predicate.ts`, `src/core/falai.ts`.
+
+## Action
+
+An action is a host function with typed parameters. A `do` step names it and passes `with`. It runs at least once per step visit, so make it idempotent: safe to run twice. Check `ctx.key` and skip work you already did for that key.
+
+### Signature
+
+```ts fragment
+interface Action<C = unknown, D = unknown, P = Record<string, unknown>> {
+  description?: string;
+  parameters: ParamDefs;
+  run(params: P, ctx: ActionCtx<C, D>): ActionResult | Promise<ActionResult>;
+}
+
+type ActionMap<C = unknown, D = unknown> = Record<string, Action<C, D>>;
+
+type ParamDefs = Record<string, ParamDef>;
+
+type ParamDef =
+  | (ScalarDef & { optional?: true })
+  | { type: "array"; items: ScalarDef; description?: string; optional?: true };
+
+interface ScalarDef<T extends ScalarType = ScalarType> {
+  type: T;                                   // "string" | "number" | "integer" | "boolean"
+  description?: string;
+  enum?: readonly (string | number)[];
+}
+
+/** The `with` shape of an action, from its parameter definitions. */
+type InferParams<P extends ParamDefs> = { /* required keys */ } & { /* optional keys? */ };
+
+interface ActionCtx<C = unknown, D = unknown> {
+  context: C;
+  data: Partial<D>;
+  input: unknown;
+  run: Run;
+  key: string;
+  dedupeKey: string;
+  silenced?: string;
+  now: Date;
+  set(patch: Partial<D>): void;
+}
+
+type ActionResult =
+  | { ok: true; detail?: string; spoke?: true }
+  | { skipped: string }
+  | { failed: string }
+  | { defer: Duration; detail: string };
+```
+
+`f.action(def)` returns the same object, with `params` typed from `parameters`:
+
+```ts fragment
+f.action<const P extends ParamDefs>(def: {
+  description?: string;
+  parameters: P;
+  run: (params: InferParams<P>, ctx: ActionCtx<C, D>) => ActionResult | Promise<ActionResult>;
+}): Action<C, D, InferParams<P>>
+```
+
+### Action fields
+
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `description` | `string` | none | For people and editors. The framework never reads it. |
+| `parameters` | `ParamDefs` | required | What `with` must carry. Every parameter is required unless `optional: true`. `{}` means the action takes nothing. |
+| `run` | `(params, ctx) => ActionResult \| Promise<ActionResult>` | required | Your code. Return one of the four results; a thrown error counts as `{ failed: error.message }`. |
+
+### ParamDef fields
+
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `type` | `"string" \| "number" \| "integer" \| "boolean" \| "array"` | required | The value's type. `array` needs `items`. |
+| `items` | `ScalarDef` | required for `array` | The type of each element. |
+| `enum` | `readonly (string \| number)[]` | none | Allowed values. Becomes a literal union in `InferParams`. |
+| `description` | `string` | none | Shown to a model that writes flows (`flowSpecSchema`). |
+| `optional` | `true` | absent | The parameter may be left out of `with`. |
+
+### ActionCtx fields
+
+| Field | Type | Meaning |
+|---|---|---|
+| `context` | `C` | The host context passed to this `turn()`. |
+| `data` | `Partial<D>` | The session's collected fields, live. |
+| `input` | `unknown` | The run's input: a mention trigger's `extract` values, an event's `payload`, a `start` input, or, for a `{ flow }` jump, its `input` when given, else the parent run's input. |
+| `run` | `Run` | The run this step belongs to: id, flow, anchor, status, visits, asked counts, outcomes. |
+| `key` | `string` | `${runId}:${stepId}:${visit}`. The same input replayed mints the same key, and a deferred action re-runs under the same key. Use it as your idempotency key. |
+| `dedupeKey` | `string` | `${flowId}:${anchor}:${nonce}`. `nonce` is the trigger key when `repeat` is `'always'`, empty for `'once'` and cooldown. The host may share it across a customer's sessions through `turn({ claims })`. |
+| `silenced` | `string \| undefined` | The host's reason the assistant may not speak. `do` steps still run while silenced; check this before sending anything the customer would read. |
+| `now` | `Date` | The agent's clock at this turn. Never read `Date.now()` inside an action. |
+| `set(patch)` | `(patch: Partial<D>) => void` | Writes fields into `data` at once, as given. Values are not coerced or checked against the field's type or `enum`. |
+
+### ActionResult and what the runner does
+
+| Result | Outcome line | Movement |
+|---|---|---|
+| `{ ok: true, detail?, spoke? }` | `do` / `ok`, no `code`, `detail` only when you gave one | `then`, or the next step. |
+| `{ skipped: reason }` | `do` / `skipped`, `code: 'action-skipped'`, `detail` = your reason, unprefixed | `then`, or the next step. |
+| `{ failed: reason }` | `do` / `failed`, `code: 'action-failed'`, `detail` = your reason, unprefixed | `onFail` if the step has one, else `then` or the next step. |
+| `{ defer: '24h', detail }` | `do` / `deferred`, `code: 'action-deferred'`, `detail` as you gave it, `until` set | The run parks. A wake with key `${runId}:${stepId}:${atMs}` goes into `schedule[]`. At fire time the same step runs again at the same visit, so `ctx.key` is unchanged. |
+| thrown error | as `{ failed: error.message }` | as `failed`. |
+
+`spoke: true` tells the runner your action itself answered the customer (it sent a template, say). Three things follow: the assistant counts as having spoken, so `lastAssistantAt` moves and silence triggers re-arm; the idle speaker stays quiet this turn; and on a message turn, a talk step in another run that was about to speak is held back with `code: 'another-reply'` and its run stays `asking`.
+
+### Behaviour
+
+- `with` is rendered before `run` sees it. `{{data.x}}`, `{{context.x}}` and `{{input.x}}` are replaced inside every string, at any depth. A path that resolves to nothing keeps its placeholder, so a typo stays visible.
+- `with` is checked when the agent is built, not on the turn that reaches the step. A missing required parameter, an unknown parameter, or a value outside `enum` throws `FlowConfigurationError`. So does a wrong type: `"3"` is not a number, because values are never coerced. A string that contains `{{` skips the `enum` check, because its value is only known at run time.
+- Actions run in the Run phase, by code, with zero model calls. They run while `silenced` too.
+- A `do` step whose action name is not registered throws at build. If the registry changed under a running agent, the step reports `code: 'action-failed'` with `detail: 'unknown action "notify"'`.
+- The runner awaits `run`. Keep it short; nothing else in the turn moves until it returns.
+
+### Example
+
+```ts
+import { falai, GeminiProvider } from "@falai/agent";
+
+const f = falai().fields({
+  nome: { type: "string", ask: "Pergunte o nome." },
+  empresa: { type: "string", ask: "Pergunte a empresa." },
+});
+
+// `params` is typed from `parameters`: { recipient: string; message: string; urgent?: boolean }.
+const notify = f.action({
+  description: "Avisa alguém da equipe.",
+  parameters: {
+    recipient: { type: "string" },
+    message: { type: "string" },
+    urgent: { type: "boolean", optional: true },
+  },
+  run: (params, ctx) => {
+    console.log(`[${ctx.key}] ${params.recipient}: ${params.message}`);
+    return { ok: true, detail: "aviso enviado" };
+  },
+});
+
+const agent = f.agent({
+  name: "Ana",
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
+  actions: { notify },
+  flows: [
+    f.flow({
+      id: "triagem",
+      name: "Triagem",
+      on: [{ message: ["quer um orçamento"] }],
+      steps: [
+        { id: "quem", collect: ["nome", "empresa"] },
+        {
+          id: "avisa",
+          do: "notify",
+          with: { recipient: "owner", message: "Lead: {{data.nome}} ({{data.empresa}})" },
+          onFail: "falhou",
+        },
+        { id: "tchau", say: "Um vendedor continua daqui.", then: "end" },
+        // The action failed: say so, and say what happens next.
+        { id: "falhou", say: "Não consegui avisar o time agora. Seus dados estão salvos e um vendedor fala com você ainda hoje." },
+      ],
+    }),
+  ],
+});
+
+const r = await agent.turn({ sessionId: "demo", message: "quero um orçamento" });
+console.log(r.outcomes.map((o) => [o.stepId, o.status, o.code, o.detail]));
+```
+
+## Event
+
+An event is a fact the host reports: a deal moved stage, a meeting was booked, a human replied. Register it by name so triggers (`on: [{ event }]`) and steps (`wait: { event }`) can use it. The definition carries a direction and a `payload` type that exists only for TypeScript; nothing is ever stored in it.
+
+### Signature
+
+```ts fragment
+interface EventDef<P = unknown> {
+  direction?: "inbound" | "outbound";
+  readonly payload?: P;   // phantom: the payload type, never set at run time
+}
+
+type EventMap = Record<string, EventDef>;
+
+f.event<P = undefined>(def?: { direction?: "inbound" | "outbound" }): EventDef<P>
+```
+
+### EventDef fields
+
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `direction` | `"inbound" \| "outbound"` | none | `'inbound'`: the customer spoke through this event. `'outbound'`: the assistant spoke. Absent: neither side spoke. |
+| `payload` | `P` | never set | Only types the payload. Never set it. |
+
+### Reporting an event
+
+The host calls `turn()` with the event variant of `TurnInput`:
+
+```ts fragment
+{ event: string; payload?: unknown; key: string; hop?: number }
+```
+
+| Field | Meaning |
+|---|---|
+| `event` | The registered name. |
+| `payload` | Becomes the run's `input`; `{{input.x}}` reads it in prompts, `say` texts and `with`. |
+| `key` | The trigger key. Runs it starts get id `${flowId}#${key}`, and with the default `repeat: 'always'` the claim `${flowId}:${anchor}:${key}` is written. Reporting the same event again with the same key starts nothing: the start is skipped with `code: 'already-claimed'`. |
+| `hop` | Chaining depth, default 0. A start that would be at hop 5 is skipped with `code: 'hop-limit'`. |
+
+An event turn never spends an understand call. It costs one speak call (plus tool rounds) only when a run it moved reaches a talk step.
+
+### What an event turn does, in order
+
+1. **Direction.** `'inbound'` sets `lastUserAt` to now and resolves reply waits: every run parked on a timer `wait` that has an `else` resumes with `code: 'replied'` and follows a matching `if` branch's `then`, else `else`. `'outbound'` sets `lastAssistantAt` to now, which re-arms `silence` triggers at the end of the turn.
+2. **Waiting runs.** Every run parked on `wait: { event: name }` for this name resumes with `code: 'event-arrived'` and follows `then`. The first one to resume takes the floor for this turn.
+3. **Triggers.** Every flow with `on: [{ event: name }]` goes through the start order: trigger `if`, `repeat` (default `'always'` for events), the hop cap, one live run per flow and anchor. With `after`, the run parks first (`code: 'awaiting-trigger'`, wake key `${runId}:start:${atMs}`) and enters its first step when the wake fires; `businessHours: true` snaps that time forward through the agent's `businessHours` function.
+
+`wait: { event, upTo }` in a step parks the run for at most `upTo` (default `'30d'`, from `src/core/Runner.ts`). If the event never comes, the line carries `code: 'no-event'` and the run follows `else`, or ends when there is none.
+
+### Example
+
+```ts
+import { falai, GeminiProvider } from "@falai/agent";
+
+interface Ctx {
+  lead: { id: string };
+}
+
+const f = falai<Ctx>().fields({
+  nome: { type: "string", ask: "Pergunte o nome." },
+});
+
+const events = {
+  stage_entered: f.event<{ stageId: string }>(),
+  reaction: f.event<{ emoji: string }>({ direction: "inbound" }),
+};
+
+const agent = f.agent({
+  name: "Ana",
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
+  events,
+  flows: [
+    f.flow({
+      id: "proposta",
+      name: "Proposta enviada",
+      // Starts on every `stage_entered`, ten minutes after it is reported.
+      on: [{ event: "stage_entered", after: "10m" }],
+      steps: [{ id: "avisa", say: "Você entrou na etapa {{input.stageId}}. Quer que eu explique os próximos passos?" }],
+    }),
+  ],
+});
+
+const r = await agent.turn({
+  sessionId: "demo",
+  context: { lead: { id: "l1" } },
+  event: "stage_entered",
+  payload: { stageId: "proposta" },
+  key: "stage:proposta:1",
+});
+console.log(r.schedule); // one wake, ten minutes from now
+```
+
+## Condition
+
+A condition is a named yes/no check in code. Flows written in TypeScript can pass a function anywhere a predicate (`Pred`, below) is accepted; flows stored as JSON cannot, so they name a condition and give it an argument: `{ tagsAny: ["vip"] }`.
+
+### Signature
+
+```ts fragment
+interface Condition<C = unknown, D = unknown, Arg = unknown> {
+  check(ctx: PredCtx<C, D>, arg: Arg): boolean;
+}
+
+type ConditionMap<C = unknown, D = unknown> = Record<string, Condition<C, D>>;
+
+/** The JSON form of a predicate. Every listed entry must hold. */
+interface ConditionSpec<D = unknown> {
+  equals?: Partial<D>;
+  known?: (keyof D & string)[];
+  silenced?: boolean;
+  [condition: string]: unknown;   // a registered condition and its argument
+}
+
+/** A code predicate (free) or its JSON form. */
+type Pred<C = unknown, D = unknown, P = unknown> =
+  | ((ctx: PredCtx<C, D, P>) => boolean)
+  | ConditionSpec<D>;
+
+interface PredCtx<C = unknown, D = unknown, P = unknown> {
+  context: C;
+  data: Partial<D>;
+  input: P;
+  run?: Run;
+  silenced?: string;
+  now: Date;
+}
+
+f.condition<Arg>(check: (ctx: PredCtx<C, D>, arg: Arg) => boolean): Condition<C, D, Arg>
+```
+
+### PredCtx fields
+
+| Field | Type | Meaning |
+|---|---|---|
+| `context` | `C` | The host context of this turn. |
+| `data` | `Partial<D>` | Collected fields, live. |
+| `input` | `P` | The run's input (see `ActionCtx.input`). `undefined` when there is no run. |
+| `run` | `Run \| undefined` | The run being judged. Present for a trigger `if`, `while`, an `if` step, a branch `if`, and a flow or step instruction `if`. Absent whenever the idle speaker answers, because no run holds the floor — for agent-level and `idle`-level instructions alike. |
+| `silenced` | `string \| undefined` | The host's reason the assistant may not speak, when given. |
+| `now` | `Date` | The agent's clock. |
+
+For a trigger `if`, `run` is the run as it would be if it started now: id `${flowId}#${triggerKey}`, `stepId: null`, `status: 'running'`, empty `asked`, `visits` and `outcomes`. Nothing has been written to the session yet.
+
+### ConditionSpec built-ins
+
+A `ConditionSpec` holds when every key holds (AND). A key whose value is `undefined` is skipped.
+
+| Key | Argument | Holds when |
+|---|---|---|
+| `equals` | `{ field: value, … }` | Every `data[field]` deep-equals the value as written. Values are compared, not rendered: `"{{context.x}}"` is a literal string here. |
+| `known` | `["field", …]` | Every field is known: not `undefined`, not `null`, not `''`. |
+| `silenced` | `true \| false` | `true`: the host passed `silenced`. `false`: it did not. |
+| any other key | anything | `conditions[key].check(ctx, arg)` returns true. The argument arrives from JSON unvalidated; test its shape inside `check`. |
+
+Naming a condition the agent does not have throws `FlowConfigurationError` when the agent is built (`validateFlow`), and again at evaluation if it ever gets that far.
+
+### Where a predicate may appear
+
+| Place | Field | Judged |
+|---|---|---|
+| Trigger | `on[].if` | Before a run starts. For `message` and `silence` triggers also earlier, when the turn works out which flows may start; `run` is then the run as it would be (see above). |
+| Flow | `while` | Every time the run is about to move. Default: the trigger's `if`. When it stops holding the run ends with `code: 'premise-changed'`. |
+| Step | `if` step | When the run reaches it. `then` on true, `else` (default `'end'`) on false. |
+| Branch | `branches[].if` | On the asking talk step when the customer writes, and on a timer `wait` when the customer replies first. |
+| Instruction | `if` | When the speak prompt is built. A false `if` drops the instruction from this call. |
+
+A function predicate is free and runs on every check. A `when` string is different: the model judges it, and it costs part of a call. See [Conditions](../guides/conditions.md).
+
+### Example
+
+```ts
+import { falai, GeminiProvider } from "@falai/agent";
+
+interface Ctx {
+  lead: { tags: string[]; owner: "ai" | "human" };
+}
+
+const f = falai<Ctx>().fields({
+  nome: { type: "string", ask: "Pergunte o nome." },
+});
+
+const conditions = {
+  // JSON flows write { tagsAny: ["vip"] }; `arg` arrives unvalidated, so check its shape.
+  tagsAny: f.condition((ctx, tags: string[]) => Array.isArray(tags) && tags.some((t) => ctx.context.lead.tags.includes(t))),
+};
+
+const agent = f.agent({
+  name: "Ana",
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
+  conditions,
+  flows: [
+    f.flow({
+      id: "vip",
+      name: "Atendimento VIP",
+      on: [{ message: ["quer falar com alguém"], if: { tagsAny: ["vip"] } }],
+      steps: [
+        // A function predicate, free, judged by code.
+        { id: "dono", if: ({ context }) => context.lead.owner === "ai", then: "quem", else: "end" },
+        { id: "quem", collect: ["nome"] },
+      ],
+    }),
+  ],
+});
+
+const r = await agent.turn({
+  sessionId: "demo",
+  context: { lead: { tags: ["vip"], owner: "ai" } },
+  message: "quero falar com alguém",
+});
+console.log(r.started.map((s) => s.flowId)); // ["vip"]
+```
+
+## See also
+
+- [Actions and events](../guides/actions-and-events.md): idempotency, publishing events, waiting on them.
+- [Conditions](../guides/conditions.md): `when` versus `if`, and where each is allowed.
+- [Flow spec](./flow-spec.md): how names in a JSON flow resolve against these registries.
+- [Outcomes](./outcomes.md): every line a `do` step or a skipped start can produce.
+- [Step](./step.md): the `do`, `if` and `wait` steps.

package/docs/reference/agent.md

@@ -0,0 +1,244 @@
+---
+title: "Agent"
+description: "How to build an agent with falai(), every AgentOptions field, and what turn() takes and returns."
+type: reference
+order: 1
+---
+
+# Agent
+
+An `Agent` is immutable configuration plus one method, `turn()`. You build it once with `falai<C>().fields(...).agent(...)`; the same instance serves every session. Each call to `turn()` brings its own `sessionId`, `session`, `context` and `history`, and returns the messages to send, the wakes to schedule and the session to save. The framework never sends, never sleeps and never saves. The program that does those three things is the host.
+
+A turn spends at most two model calls: the understand call, which routes the message and pulls values out of it, and the speak call, which phrases the reply.
+
+## Signature
+
+```ts fragment
+function falai<C = undefined>(): FalaiRoot<C>;
+
+interface FalaiRoot<C> {
+  fields<const F extends FieldDefs>(defs: F): Falai<C, InferData<F>, F>;
+  // plus every Falai method below, with loose data (any slug is a string)
+}
+
+interface Falai<C, D, F extends FieldDefs> {
+  readonly fields: F;
+  action<const P extends ParamDefs>(def: {
+    description?: string;
+    parameters: P;
+    run(params: InferParams<P>, ctx: ActionCtx<C, D>): ActionResult | Promise<ActionResult>;
+  }): Action<C, D, InferParams<P>>;
+  event<P = undefined>(def?: { direction?: "inbound" | "outbound" }): EventDef<P>;
+  condition<Arg>(check: (ctx: PredCtx<C, D>, arg: Arg) => boolean): Condition<C, D, Arg>;
+  flow(def: Flow<C, D>): Flow<C, D>;
+  fromSpec(spec: FlowSpec): Flow<C, D>;
+  agent(options: Omit<AgentOptions<C, D>, "fields">): Agent<C, D>;
+}
+
+type DataOf<T extends { fields: FieldDefs }> = InferData<T["fields"]>;
+
+class Agent<C, D> {
+  constructor(readonly options: AgentOptions<C, D>);
+  turn(input: TurnInput<C, D>): Promise<TurnResult<D>>;
+  turnStream(input: TurnInput<C, D>): AsyncIterable<TurnStreamChunk<D>>;
+}
+```
+
+## The toolkit
+
+`falai<C>()` takes one generic: the type of the `context` your host passes on every turn. `falai()` alone means no context. Everything else is inferred from values.
+
+| Method | Returns | What it does |
+|---|---|---|
+| `fields(defs)` | `Falai<C, D, F>` | Binds the collected-data type `D`. Every `collect`, `ask`, `clearOnStart`, `equals`, `known` and action `ctx.set` downstream is checked against these slugs. |
+| `fields` (property) | `F` | The definitions you passed, unchanged. `DataOf<typeof f>` reads the data type from it. |
+| `flow(def)` | `Flow<C, D>` | Returns the flow unchanged, typed. See [Flow](flow.md). |
+| `fromSpec(spec)` | `Flow<C, D>` | A stored JSON flow as a typed flow. Validated when the agent is built. See [Flow spec](flow-spec.md). |
+| `action(def)` | `Action<C, D, P>` | A host action. `params` inside `run` is typed from `parameters`. |
+| `event<P>(def?)` | `EventDef<P>` | A host event; `P` is its payload type. `direction` says whether it counts as the customer or the assistant speaking. |
+| `condition(check)` | `Condition<C, D, Arg>` | A named code predicate that JSON flows may use by name. |
+| `agent(options)` | `Agent<C, D>` | Builds the agent. `fields` comes from the toolkit; you pass everything else. |
+
+`Agent` is also exported directly: `new Agent(options)` takes the same options with `fields` included.
+
+## AgentOptions
+
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `name` | `string` | required | The assistant's name. Both model calls open with "You are `name`". |
+| `goal` | `Template` | none | What the agent is for. Rendered into the prompt. |
+| `persona` | `Template` | none | Who the agent is and how it talks. |
+| `provider` | `AiProvider` | required | The model. See [Providers](providers.md). |
+| `fields` | `FieldDefs` | from the toolkit | Every collectable field, authored once. See [Fields](fields.md). |
+| `flows` | `Flow<C, D>[]` | `[]` | The flows. Ids must be unique. |
+| `actions` | `ActionMap<C, D>` | `{}` | Host actions that `do` steps name. |
+| `events` | `EventMap` | `{}` | Host events that `event` triggers and `wait: { event }` steps name. |
+| `conditions` | `ConditionMap<C, D>` | `{}` | Host conditions that JSON predicates name. |
+| `tools` | `Tool<C, D>[]` | `[]` | Functions the model may call while it speaks. See [Tool](tool.md). |
+| `instructions` | `Instruction<C, D>[]` | `[]` | Agent-level rules, rendered into every speak call. See [Instruction](instruction.md). |
+| `knowledgeBase` | `Record<string, unknown>` | none | Any JSON the model should know. Rendered as nested bullets. |
+| `idle` | `Idle<C, D>` | `{ prompt: "" }` | The one speaker that is not a step. Answers a message when no run holds the floor. `'silent'` mutes it. |
+| `clock` | `Clock` | `() => new Date()` | Returns "now". Tests pass `fakeClock(iso)`. |
+| `businessHours` | `BusinessHours<C>` | none | `(at, { context }) => Date`. Moves a timer forward to the next working moment when a trigger or wait says `businessHours: true`. |
+| `maxToolLoops` | `number` | `5` | Tool rounds per speak call. `0` disables tools. After the last round the model is asked once more without tools, so a message always comes back. |
+| `compaction` | `AgentCompactionConfig` | none | Trims the history both calls see, once per turn, when it grows past `maxTokens`. See [Compaction](../guides/compaction.md). |
+| `debug` | `boolean` | `false` | Sets the logger to debug level. |
+
+`Idle` is `{ prompt: Template; tools?: string[]; instructions?: Instruction[] } | 'silent'`. Its `tools` list must name tools registered on the agent.
+
+`AgentCompactionConfig` is `{ maxTokens: number; compactionThreshold?: number; preserveRecentCount?: number; maxToolResultChars?: number; enabled?: boolean }`. Defaults: `compactionThreshold` `0.8` — compaction runs when the history passes 80% of `maxTokens` (allowed 0.5 to 0.95); keep the 4 most recent messages (at least 2); cut each tool result at 5000 characters (more than 0); `enabled: true`. Values outside those ranges throw at construction.
+
+## turn()
+
+`turn(input)` runs one turn and resolves to a `TurnResult`. It never throws for a model failure during the speak call; that becomes a retry wake (see [Error handling](../guides/error-handling.md)). A failure during the understand call does throw, and nothing was written: replay the same input.
+
+`turnStream(input)` runs the same turn and yields `{ delta: string }` chunks while the model phrases the reply, then one `{ done: true, result: TurnResult }`. When nobody speaks, only the last chunk comes. See [Streaming](../guides/streaming.md).
+
+## TurnInput
+
+Every input carries the common fields, plus exactly one of the four kinds.
+
+### Common fields
+
+| Field | Type | Meaning |
+|---|---|---|
+| `sessionId` | `string` | The conversation's id. A first turn creates the session under this id. |
+| `session` | `Session<D>` | The stored session, as the store returned it. Absent on a first turn. A `wake` without a session is ignored. |
+| `context` | `C` | Your ambient data for this turn. Required unless `C` allows `undefined` (`falai()` with no generic). |
+| `history` | `History` | The conversation so far. Pass it on every input kind, wakes included; both calls read it. Without it the framework falls back to `session.history`, then to an empty list. |
+| `silenced` | `Silenced` | Your reason the assistant cannot speak right now. See below. |
+| `anchors` | `Record<string, { key: string; lastInboundAt?: string }>` | The host anchors this session belongs to, by name, e.g. `{ lead: { key: 'lead:456', lastInboundAt } }`. A flow with `anchor: 'lead'` keys its runs and claims by `anchors.lead.key`. |
+| `claims` | `{ held: Record<string, string>; active: string[] }` | Claims from the customer's other sessions: `held` maps a dedupe key to the ISO time it was taken; `active` lists live `${flowId}:${anchor}` pairs. A flow already active elsewhere is skipped with `code: 'already-running'`. |
+
+### The four kinds
+
+| Kind | Shape | When to send it |
+|---|---|---|
+| message | `{ message: string; id?: string; at?: string }` | The customer wrote. `id` is the channel's message id; a repeated `id` is ignored (`code: 'duplicate-input'`, `changed: false`). `at` is the receipt time; it defaults to the clock's now. |
+| wake | `{ wake: string }` | A `schedule[]` entry fired. Pass its `key`. A `silence:` key starts that flow's silence run, and only while the silence still holds (`code: 'silence-broken'` otherwise). Any other key moves only the run whose wait holds it exactly; anything else is `code: 'stale-wake'`. |
+| event | `{ event: string; payload?: unknown; key: string; hop?: number }` | Something happened in the host. `event` names a registered event; `key` is your idempotency key for it; `payload` becomes the run's `input`. |
+| start | `{ start: { flow: string; input?: unknown; key: string; hop?: number } }` | Start a flow by hand. Works for any flow, with or without `on`. |
+
+### Silenced
+
+```ts fragment
+type Silenced = string | { reason: string; understand?: boolean };
+```
+
+A string closes the gate: `do` steps still run, nothing is phrased, zero model calls. A talk or `say` step reached while the gate is closed ends its run with `code: 'silenced'` (`detail` = your reason); a run that was already asking stays asking and speaks when the gate opens. `{ reason, understand: true }` keeps the understand call on, so routing, mentions and extraction still happen while the assistant stays quiet. Predicates see the reason as `ctx.silenced`.
+
+## TurnResult
+
+| Field | Type | Meaning |
+|---|---|---|
+| `session` | `Session<D>` | The session after this turn. `version` is unchanged; the host saves it with the version it loaded and the store bumps it. |
+| `changed` | `boolean` | `false` means save nothing and send nothing: the input was ignored or nothing moved. |
+| `messages` | `OutboundMessage[]` | What to send, in order. |
+| `schedule` | `ScheduleEntry[]` | Wakes to enqueue with `jobId = key`. At fire time call `turn({ wake: key })`. |
+| `outcomes` | `StepOutcome[]` | One line per step this turn, for your execution log. See [Outcomes](outcomes.md). |
+| `started` | `Array<{ runId; flowId; anchor; dedupeKey }>` | Runs that started this turn. |
+| `ended` | `Array<Run & { reason: EndReason }>` | Runs that ended, with the run's last state and why: `'end'`, `'flow'`, `'reset'`, `'skipped'`, `'failed'` or `'replaced'`. |
+| `skipped` | `Array<{ flowId; anchor; triggerKey; code; message }>` | Triggers that matched but did not start a run, and why (`code: 'already-claimed'`, `code: 'cooldown'`, `code: 'already-running'`, `code: 'hop-limit'`, `code: 'flow-gone'`). |
+| `llmCalls` | `number` | Model calls this turn: at most one understand call, plus one speak call and one per tool round, plus one when compaction summarized. |
+| `usage` | `TokenUsage` | What those calls cost, added up. Absent when the turn spent no call, and when the provider reported no counts. |
+
+### TokenUsage
+
+```ts
+interface TokenUsage {
+  promptTokens: number;
+  completionTokens: number;
+  cachedInputTokens: number;
+}
+```
+
+| Field | Type | Meaning |
+|---|---|---|
+| `promptTokens` | `number` | Tokens read, the cached ones included. |
+| `completionTokens` | `number` | Tokens written. Thinking tokens count here. |
+| `cachedInputTokens` | `number` | The part of `promptTokens` the provider served from its cache, billed far cheaper. `0` when the provider caches nothing or the prefix was cold. |
+
+The counts are the providers' own, summed over every call the turn made. `usage` is absent rather than zero when nobody counted, so an unreported turn never looks free:
+
+```ts fragment
+const r = await agent.turn({ sessionId: "s1", message: "oi" });
+if (r.usage) {
+  const fresh = r.usage.promptTokens - r.usage.cachedInputTokens;
+  console.log(`${r.llmCalls} call(s): ${fresh} read, ${r.usage.cachedInputTokens} cached, ${r.usage.completionTokens} written`);
+}
+```
+
+### OutboundMessage
+
+| Field | Type | Meaning |
+|---|---|---|
+| `text` | `string` | The message. |
+| `kind` | `'ai' \| 'verbatim'` | `'ai'` was phrased by the model; `'verbatim'` came from a `say` step. |
+| `media` | `{ slug: string }` | From a `say` step's `media`. |
+| `afterMs` | `number` | Delay before sending. A `wait` of 10 seconds or less right before a `say` or talk step lands here instead of scheduling a wake. |
+| `key` | `string` | `${runId}:${stepId}:${visit}` for a step; `idle:${triggerKey}` for the idle speaker. The same on a replay of the same input, so your sender can dedupe on it. |
+| `runId`, `stepId` | `string` | Which run and step spoke. Absent for the idle speaker. |
+
+### ScheduleEntry
+
+| Field | Type | Meaning |
+|---|---|---|
+| `key` | `string` | The wake key. Use it as the job id and pass it back as `turn({ wake: key })`. |
+| `at` | `Date` | When to fire. |
+| `replaces` | `string` | An earlier wake this one supersedes. Removing it is best effort; a stale wake is ignored anyway. |
+
+## Behaviour
+
+- **Construction validates everything.** `f.agent()` throws `FlowConfigurationError` when:
+  - two flows share an id
+  - `idle.tools` names a tool that is not registered
+  - a tool's `parameters` is not a JSON Schema object (`{ type: "object", properties, required }`) — the shape a function declaration needs, and easy to confuse with an action's `{ name: { type } }` map
+  - `validateFlow` rejects any flow (see [Flow](flow.md#what-validateflow-rejects))
+
+  Warnings — a backward jump without `clear`, a `collect` with no prompt and no `ask` — are logged with the `[Agent]` prefix. Compaction options outside their ranges throw a plain `Error`.
+- **The input is never mutated.** `turn()` deep-copies `session` and works on the copy. `result.session` is that copy.
+- **Ignored inputs.** A wake with no `session`, a wake whose key no live run holds, a silence wake after the customer wrote, and a message whose `id` is in the session's last 50 input ids all return `changed: false` with one `skipped` outcome line whose `code` says which: `no-session`, `stale-wake`, `silence-broken` or `duplicate-input`.
+- **`changed` is computed, not flagged.** It is `true` when the session differs from the one you passed, or when there is anything in `messages`, `schedule`, `outcomes` or `skipped`.
+- **Keys are deterministic.** Run id `${flowId}#${triggerKey}`, step key `${runId}:${stepId}:${visit}`. Replaying the same input against the same session version mints the same keys. See [Session](session.md) for the full table.
+- **One speaker per turn.** At most one run asks at a time (the floor). A `say` or an action that reports `spoke: true` from another run makes the floor's talk step wait for the next message (`code: 'another-reply'`). The idle speaker answers a message only when no run is asking and nothing else spoke.
+- **`context` is passed through as is.** Templates read it as `{{context.x}}`; predicates, actions and tools get it on `ctx.context`.
+
+## Example
+
+```ts
+import { falai, GeminiProvider } from "@falai/agent";
+
+const f = falai().fields({
+  nome: { type: "string", ask: "Pergunte o nome da pessoa, sem tom de formulário." },
+});
+
+const agent = f.agent({
+  name: "Ana",
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
+  flows: [
+    f.flow({
+      id: "boas-vindas",
+      name: "Boas-vindas",
+      on: [{ message: [] }],
+      steps: [
+        { id: "nome", collect: ["nome"] },
+        { id: "ajuda", prompt: "Agradeça pelo nome e pergunte como pode ajudar." },
+      ],
+    }),
+  ],
+});
+
+const first = await agent.turn({ sessionId: "s1", message: "oi", id: "m1" });
+console.log(first.messages[0]?.text, first.llmCalls); // the question for `nome`, 1
+
+const second = await agent.turn({ sessionId: "s1", session: first.session, message: "sou a Ana", id: "m2" });
+console.log(second.session.data.nome, second.messages[0]?.key, second.llmCalls); // 'Ana', 'boas-vindas#m1:ajuda:1', 2
+```
+
+## See also
+
+- [Flow](flow.md), [Step](step.md), [Trigger](trigger.md), [Fields](fields.md)
+- [Session](session.md) for `Session`, `Run` and the key formats
+- [Outcomes](outcomes.md) for every outcome code
+- [Architecture](../concepts/architecture.md) and [Pipeline](../concepts/pipeline.md)
+- [Go to production](../start/05-go-to-production.md) for the host loop