Module flow 

Flow — a governed conversation/tool DAG.

A Flow is a directed acyclic graph of Steps. A Step is the only node type; it unifies “conversation stage” and “tool-call milestone” by differing only in attributes, not in kind. A step is done when its completion Guard latches true; edges (after) are dependencies. The FlowMonitor maintains a Marking (the set of done steps) by observing the session trace, projects active steps’ postures into turn-boundary steering, and enforces ordering by admitting/denying tool calls.

The vocabulary is deliberately closed: the only nouns are Flow, Step, Guard, Posture, Marking, Verdict. Words like phase, transition, watch, needs are lowering details and never appear here.

Because every Guard atom is a named, parameterized predicate, a Flow is fully serializable — enabling data-driven scripts edited without a recompile. The custom closure escape hatch is available in code but is not serializable.

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.

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).

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).

Violation

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

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.

Verdict

The conformance status of a step.

Functions

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.

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.