## React Mode (Plan–Act–Observe–Refine)

This introduces a compact iterative workflow that replaces bulk action plans with a tight loop:

- Plan (select): Model selects exactly one action
- Act (execute): Host requests only parameters for that action and executes
- Observe (summarize): Host returns a compact observation object
- Refine (decide): Model decides whether to continue or stop

### How to enable it

Set the mode on `ChatWorkflow` (persisted in DB / passed through the API):

- `workflowMode: string` – "Actionplan" (legacy) or "React" (iterative)
- `maxSteps: number` – maximum iterations per task in React mode (default 5)

When `workflowMode="Actionplan"`, the legacy batch action planning path is used.

### Data models

Defined in `gateway/modules/interfaces/interfaceChatModel.py`:

- `ActionSelection`: `{ method: str, name: str }`
- `ActionParameters`: `{ parameters: dict }`
- `Observation`: `{ success: bool, resultLabel: str, documentsCount: int, previews: [{name,mime,snippet}], notes: [str] }`
- `TaskContext` additions: `reactMode: bool`, `maxSteps: int`
- `ChatWorkflow` additions: `workflowMode: str`, `maxSteps: int`

### Prompts

Defined in `gateway/modules/chat/handling/promptFactory.py`:

- `createActionSelectionPrompt(context)` → returns one action
- `createActionParameterPrompt(context, selected_action)` → returns parameters only
- `createRefinementPrompt(context, observation)` → returns `{ decision: continue|stop, reason }`

### Execution flow

Implemented in `gateway/modules/chat/handling/handlingTasks.py`:

- `plan_select(context)` → `{ action: { method, name } }`
- `act_execute(context, selection, task_step, workflow, step)` → executes one action and returns `ActionResult`
- `observe_build(action_result)` → builds `Observation`
- `refine_decide(context, observation)` → `{ decision, reason }`
- Integrated loop lives inside `executeTask(...)` when `context.reactMode` is true

Iteration control helper in `gateway/modules/chat/handling/executionState.py`:

- `should_continue(observation, review_dict, current_step, max_steps)`

### Observation format

Compact, machine-friendly, with small previews only:

```
{
  success: boolean,
  resultLabel: string,
  documentsCount: number,
  previews: [ { name, mime, snippet } ],
  notes: [ string ]
}
```

### Telemetry

Each iteration logs duration (seconds) to workflow logs. No specific token metrics required.

### Backward compatibility

- Legacy planning/execution remains the default when `workflowMode="Actionplan"`.
- No breaking changes to action or document structures.

### Notes

- Document routing uses deterministic `resultLabel`: `round{r}_task{t}_action{a}_...`
- Previews are capped to ≤5 items and keep `name`, `mime`, and a short `snippet`.