Module flow 

Governed-conversation flow primitives: Flow, Step, Guard, FlowMonitor.

Modules

stack

FlowStack — the runtime above the DAG: a main flow plus its digressions.

timing

Voice timing per stage: how the conversation sounds while a step is active.

verbatim

Verbatim stages: text the model must say word for word, verified.

Structs

CompiledFlow

A validated Flow plus its precomputed ToolSurface.

Edge

A dependency edge into a step.

Flow

A governed conversation/tool DAG.

FlowBuilder

Builder for a Flow using the cemented verbs.

FlowCtx

Evaluation context handed to a Guard: the session state plus the current flow marking.

FlowErrors

All problems found while compiling a Flow; non-empty on failure.

FlowExplanation

A model-readable explanation of the current control-plane state — the foundation of why did the assistant ask that?.

FlowMonitor

Observes the session trace, maintains the Marking, answers tool admissibility, and projects active postures.

FlowStack

The main flow plus its digressions, with push-on-trigger and resume-on-completion.

GuardTrace

A Guard evaluated to a truth tree: each predicate node with its prose description and whether it currently holds. Serializable, so a devtool can render exactly which atom a stuck step is waiting on.

Marking

The runtime position in a flow: which steps are done and how often each tool has succeeded.

NeverBuilder

Sub-builder for never(tool).until(guard).

Overlay

A digression the runtime can enter: its trigger, governed flow and resume policy. Built from a compiled flow so it carries proof of compilation.

RepairPolicy

A step’s repair policy for the weird paths (silence, no-match, the user stalling). The stack sets repair:{step}:reprompt once the step has been active reprompt_after turns without completing, and repair:{step}:escalate after escalate_after. When escalate_to is set, the authoring layer lowers an extra edge gated on the escalate signal — a deterministic “give up and hand off”.

ResetBuilder

Intermediate for reset(steps).when(guard).

Step

A node in the flow DAG — the only node type.

StepAction

An action fired the first time a step becomes active: run an agent in an AgentMode. Built with on_enter. The result lands in {name}:result (the name defaults to the step id), so a downstream step can complete on it via Guard::resolved — this is how a flow drives orchestration in-session.

ToolSurface

The precomputed tool surface of a compiled flow: every tool name the flow reasons about (step allow/deny, once, never…until, confirm), so introspection can enumerate and explain gating decisions. Distinct from tool::ToolPolicy, which is a per-tool runtime policy (timeout/cache/confirm).

VerbatimRequirement

The published requirement of the active verbatim stage.

Violation

A recorded conformance deviation (observe mode) or denial (enforce mode).

VoiceTiming

Voice pacing for one stage. Every field is optional; an unset field leaves the session’s own behaviour alone.

Enums

Constraint

A cross-cutting flow constraint.

Enforcement

How a FlowMonitor treats off-path activity — enforcement vs observation.

FlowError

A single problem found while compiling a Flow.

Guard

A boolean predicate over (state, marking) — the only predicate type.

Join

How a step’s dependency edges combine.

Pred

A serializable predicate atom — the closed set of guard primitives.

Resume

How the main flow continues after a digression (overlay) completes.

Verdict

The conformance status of a step.

Constants

DEFAULT_REPROMPT

The reprompt sent when a stage sets reprompt_after_ms but no text.

OVERLAY_STATE_KEY

The state key that names the active digression (null when the main flow is driving). Published by the control plane at every turn boundary.

TERMINATED_STATE_KEY

The state key raised (true) once a Resume::Terminate digression has ended the conversation. Governance is inert from then on: no postures, no admitted tools. The runtime does not hang up by itself — the application decides how a call ends — so watch this key (or FlowStack::is_terminated) and close the session. Published by the control plane at every turn boundary.

TOOL_CALL_KEY

Written when the governed flow admits a tool call, before it runs: {"tool": name, "id": call id}. With TOOL_DENIED_KEY and TOOL_RESULT_KEY it puts every governance decision about a tool in the mutation journal, in order, which is what makes a recorded session replayable as a scenario.

TOOL_DENIED_KEY

Written when the governed flow refuses a tool call: {"tool": name, "id": call id, "reason": why}.

TOOL_RESULT_KEY

Written when an admitted tool call completes: {"tool": name, "id": call id, "ok": succeeded}.

VERBATIM_KEY

The state key under which the active verbatim requirement is published.

VOICE_TIMING_KEY

The state key the active stage’s merged timing is published under.

Functions

correction_flag

The state key raised for one turn when the user corrects slot: its value changed from one captured value to another. See FlowStack::with_correction.

escalate_flag

The state key raised when a stage’s repair policy escalates.

on_enter

Build a step-enter action that runs agent in mode when the step first activates. Pair with FlowMonitor::on_enter.

render_ground

Render a grounding template against state.

reprompt_flag

The state key raised when a stage’s repair policy asks for a reprompt.

verbatim_flag

The state key holding whether step’s text was said verbatim.

Type Aliases

SharedFlowMonitor

A shared, lock-protected FlowMonitor — the form in which the Live control plane owns a governed flow, so runtime surfaces (e.g. LiveHandle::explain) can snapshot it concurrently. All monitor methods are synchronous: lock briefly and never hold the guard across an await.

SharedFlowStack

A shared, lock-protected FlowStack — the form in which the Live control plane owns governance, so runtime surfaces (e.g. LiveHandle::explain) can snapshot it concurrently. All methods are synchronous: lock briefly and never hold the guard across an await.