Module interaction_points 

Declarative stage-boundary interaction points (StageMode::InteractivePoints).

Unlike the model-driven ask_user_* / edit_document tools (which fire only if the model chooses to call them - see crate::dynamic_interaction), an interaction point is declared statically in the blueprint and fired by the framework at the stage boundary, always, before the stage may transition. The canonical example is plan_approval: after the plan stage produces a plan, the user is shown a choice - approve / revise / edit / abort - and the answer deterministically routes what happens next.

This is a first-class ECS lane, mirroring the transition-choice lane:

• gate_interaction_points intercepts a would-be transition (ResolveTransition) for an interactive-points stage and instead marks the agent ReadyForInteractionPoint.
• dispatch_interaction_point spawns an async task that asks through the shared InteractionHub (so the dashboard surfaces the prompt via reflect_interaction_status), resolves the answer, and reports a PointOutcome on the lane.
• collect_interaction_point applies the outcome: approve ⇒ proceed to the transition, abort ⇒ cancel the run, a directive ⇒ inject it and re-run inference in-stage, an edit ⇒ inject the edited text and re-present the point. Directive/edit loops are bounded by MAX_REVISION_ROUNDS.

The routing is deterministic (code); only the input capture is a user interaction - faithfully porting the deleted imperative run_interactive_points_stage.

Structs

AwaitingInteractionPoint

An interaction point is in flight (its request is open in the hub); the collect system applies the answer when the lane reports it.

InteractionPointCursor

Which interaction point (index into the stage’s points) the agent is on. Absent ⇒ 0. Advanced on approve; reset when a new stage is entered.

InteractionPointOutcome

One resolved interaction-point answer, reported on the lane.

InteractionPointResults

The receiving side of the interaction-point lane, for the collect system.

InteractionPointRounds

How many directive/edit revision rounds have been taken at the current point. Absent ⇒ 0. Reset on approve (advancing points) and on entering a new stage.

InteractionPointStage

The sending side of the interaction-point lane + the handle/wake needed to drive the async ask task, as a world resource.

InteractionPointState

Serializable snapshot of an agent parked at a stage-boundary interaction point, persisted to <run_dir>/interactions.json so a daemon restart can re-present the exact same prompt instead of dropping it and re-issuing inference. Mirrors the fan-out sidecar (fanout.json). Everything needed to resume is small: the reviewed document lives here (and in a persisted context region), and the request id is derived from the agent id + point name + round.

PlanBodyOverride

The authoritative document to present as the point’s body on the next dispatch, overriding the last inference response. Set when the user edits the document directly (so the re-presented approval shows the edited text, not the pre-edit version) and consumed on the next dispatch.

ReadyForInteractionPoint

The agent’s current stage is done and has an unsatisfied interaction point; the dispatch system should ask it. (Set by the gate or by an edit re-present.)

Enums

PointOutcome

What the user’s answer resolved to, routed deterministically from the option label. Carries the text the collect system must inject into context.

Constants

MAX_REVISION_ROUNDS

Maximum directive/edit revision rounds at one interaction point before the stage proceeds regardless, so a revise/edit loop can never run forever.

Functions

collect_interaction_point

Collect: apply each resolved interaction-point outcome - approve advances (or transitions when all points are done), abort cancels, a directive injects the directive and re-infers in-stage, an edit injects the edited text and re-presents; both revision paths are bounded by MAX_REVISION_ROUNDS.

dispatch_interaction_point

Dispatch: for each ReadyForInteractionPoint agent, spawn the ask task for its current point and move it to AwaitingInteractionPoint. No hub (test world) ⇒ no-op; a non-interactive stage ⇒ fall back to the transition.

gate_interaction_points

Gate: intercept a would-be transition for an interactive-points stage whose points aren’t all satisfied yet, routing the agent to the interaction-point lane instead. Stages with no points, or whose point cursor is past the end (all approved), fall through to the normal transition.

restore_interaction_point

Re-arm an agent that was blocked at an interaction point when the daemon stopped, bringing it back in the waiting state with the same open request - rather than the default Active + ReadyToInfer restore, which would re-issue inference and drop the prompt.