Outcomes

A turn writes one line per thing a run did: a step ran, a step was skipped, a run parked, a value was dropped. Those lines are StepOutcomes. They come back on TurnResult.outcomes and stay on each run as run.outcomes (the last 50). Beside them, TurnResult.started, ended and skipped say which runs began, which ended and why, and which triggers matched but started nothing. This page lists every line the code can write, so a panel that shows runs can label each one.

Source: src/types/session.ts, src/types/agent.ts, src/core/Runner.ts, src/core/Speak.ts, src/utils/outcomes.ts, src/utils/schema.ts.

Signature

tsCopy
type StepOutcomeKind = "prompt" | "collect" | "say" | "do" | "wait" | "if" | "idle";
type StepOutcomeStatus = "ok" | "skipped" | "failed" | "waiting" | "deferred";

type StepOutcomeCode =
  // The turn refused the input
  | "no-session" | "duplicate-input" | "stale-wake" | "silence-broken"
  // A trigger matched but started nothing
  | "already-claimed" | "cooldown" | "hop-limit" | "already-running" | "flow-gone"
  // A run ended early
  | "step-loop" | "step-gone" | "customer-replied" | "premise-changed" | "silenced"
  // A step
  | "already-known" | "asked-fixed" | "fixed-in-reply" | "another-reply" | "already-sent" | "branch" | "max-asks"
  | "inline-delay" | "awaiting-trigger" | "awaiting-event" | "event-arrived"
  | "no-event" | "replied" | "no-reply"
  // A host action
  | "action-skipped" | "action-failed" | "action-deferred"
  // A value the model gave
  | "unknown-field" | "bad-value" | "not-in-enum"
  // The model
  | "provider-unavailable" | "provider-quota" | "provider-auth"
  | "provider-context" | "provider-invalid";

interface StepOutcome {
  runId?: string;
  flowId?: string;
  stepId?: string;
  key?: string;
  kind: StepOutcomeKind;
  status: StepOutcomeStatus;
  /** Why. Absent when the line needs no reason. Switch on this. */
  code?: StepOutcomeCode;
  /** The English sentence for `code`, filled by the framework. */
  message?: string;
  detail?: string;
  next?: string;
  until?: string;
  at: string;
  llmCalls?: number;
}

type EndReason = "end" | "flow" | "reset" | "skipped" | "failed" | "replaced";

interface TurnResult<D = unknown> {
  outcomes: StepOutcome[];
  started: Array<{ runId: string; flowId: string; anchor: string; dedupeKey: string }>;
  ended: Array<Run & { reason: EndReason }>;
  skipped: Array<{ flowId: string; anchor: string; triggerKey: string; code: StepOutcomeCode; message: string }>;
  llmCalls: number;
  // session, changed, messages, schedule: see Agent
}

StepOutcome fields

Statuses

Where lines land

• TurnResult.outcomes: every line of this turn, in order, run lines and no-run lines alike.
• run.outcomes: the run's own lines, kept to the last 50, on the run inside session.runs and inside TurnResult.ended.
• TurnResult.changed is false when the input was ignored; the one ignored-input line is still on outcomes so you can log it, but there is nothing to save or send.

Every code

Grouped by what produced it. kind and status are given as kind / status. A blank code cell means the line carries no code at all.

The input was ignored

wait / skipped, no run, key = the input's key, changed: false.

Waits and wakes

Talk steps (prompt / collect)

Say steps

Do steps

The action's own words arrive in detail, unprefixed, exactly as it returned them.

If steps

Values the model gave

collect / skipped, no run, detail = the field slug. The understand or speak call reported a value that could not be written.

Tool data is written without these checks and never produces these lines.

The idle speaker

No run.

A run ended early

The run leaves session.runs, appears in TurnResult.ended, and writes one line whose kind is the current step's kind, or if when the run had not entered a step yet.

End reasons

TurnResult.ended carries each ended run with its reason:

Triggers that matched but started nothing

TurnResult.skipped entries have { flowId, anchor, triggerKey, code, message } and write no StepOutcome.

A trigger whose if is false starts nothing and writes nothing.

Example

tsCopy
import { falai, GeminiProvider } from "@falai/agent";

const f = falai().fields({
  nome: { type: "string", ask: "Pergunte o nome." },
});

const agent = f.agent({
  name: "Ana",
  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
  flows: [
    f.flow({
      id: "triagem",
      name: "Triagem",
      on: [{ message: [] }], // no examples: the catch-all, starts when no other message flow wins
      steps: [
        { id: "quem", collect: ["nome"] },
        { id: "tchau", say: "Obrigada, {{data.nome}}. Um vendedor continua daqui." },
      ],
    }),
  ],
});

const r = await agent.turn({ sessionId: "demo", message: "oi, sou a Ana" });

for (const line of r.outcomes) {
  console.log(`${line.stepId ?? "-"} ${line.kind}/${line.status} ${line.code ?? ""} ${line.detail ?? ""} → ${line.next ?? ""}`);
}
for (const run of r.ended) console.log(`${run.id} ended: ${run.reason}`);
for (const skip of r.skipped) console.log(`${skip.flowId} not started: ${skip.code}`);
console.log(`model calls: ${r.llmCalls}`);

See also

• Runs and waits: statuses, the floor, wakes and the key table.
• Session: Run, RunStatus and where outcomes live.
• Error handling: what a deferred talk step means for the host.
• Actions, events, conditions: ActionResult and the do lines.