# FlowDrop Interrupt

> Human-in-the-loop interrupt system that pauses workflows to request user input via confirmations, choices, text, or JSON schema forms.

## Overview

The `flowdrop_interrupt` module enables workflows to pause execution and request user input. When a workflow reaches an interrupt node, it creates an interrupt request entity, pauses the pipeline, and waits for the user to respond. Once resolved, the pipeline resumes from where it left off.

Four interrupt types are provided out of the box: confirmation (yes/no), choice selection, free-text input, and JSON schema-driven forms. The module integrates with both pipeline-based execution and session-based interactive workflows.

## Dependencies

- [flowdrop](flowdrop.md)
- [flowdrop_orchestration](flowdrop_orchestration.md) (orchestrator integration)
- [flowdrop_pipeline](flowdrop_pipeline.md) (pipeline pause/resume)
- [flowdrop_job](flowdrop_job.md) (job state management)
- [flowdrop_session](flowdrop_session.md) (session-aware interrupts)
- [flowdrop_node_category](flowdrop_node_category.md) (node categorization)
- `drupal:user`

## Configuration

### Permissions

| Permission | Description |
|------------|-------------|
| `administer flowdrop interrupts` | Full administrative access. Restricted. |
| `view flowdrop interrupts` | View interrupt requests |
| `resolve flowdrop interrupts` | Respond to interrupt requests |
| `cancel flowdrop interrupts` | Cancel pending interrupt requests |

## Tips and Tricks

### Interrupt Types

| Type | Use Case | Node Processor |
|------|----------|----------------|
| **Confirmation** | Yes/No decisions (e.g., "Proceed with deletion?") | `ConfirmationNode` |
| **Choice** | Select from predefined options (single or multiple) | `ChoiceNode` |
| **Text Input** | Free-form text collection (e.g., "Enter a reason") | `TextInputNode` |
| **Form Input** | Structured data via JSON Schema forms | `FormInputNode` |

### Interrupt Resolution Flow

```
Workflow reaches interrupt node
    → InterruptManager creates interrupt entity (status: pending)
    → Pipeline pauses, job marked as interrupted
    → User resolves via API (POST /api/flowdrop/interrupts/{id})
    → InterruptResolvedSubscriber resets job to pending
    → Pipeline resumes execution
```

### Session-Aware Interrupts

When interrupts occur within a [session](flowdrop_session.md) context, the `SessionInterruptResolvedSubscriber` handles additional session state updates and message creation, keeping the interactive UI in sync.

## Developer API

### Services

| Service ID | Class | Description |
|-----------|-------|-------------|
| `flowdrop_interrupt.manager` | `InterruptManager` | Creates, resolves, cancels, and queries interrupt requests |
| `flowdrop_interrupt.interrupt_resolved_subscriber` | `InterruptResolvedSubscriber` | Resets interrupted jobs and resumes pipeline execution |
| `flowdrop_interrupt.session_interrupt_resolved_subscriber` | `SessionInterruptResolvedSubscriber` | Session-aware interrupt resolution (higher priority) |

### Entities

#### FlowDropInterrupt (Content Entity)

Stores interrupt requests with the interrupt type, prompt/configuration, response data, and status (pending, resolved, cancelled).

### API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/flowdrop/interrupts/{interrupt_id}` | Get interrupt details |
| POST | `/api/flowdrop/interrupts/{interrupt_id}` | Resolve an interrupt (submit response) |
| POST | `/api/flowdrop/interrupts/{interrupt_id}/cancel` | Cancel a pending interrupt |
| GET | `/api/flowdrop/playground/sessions/{session_id}/interrupts` | List interrupts for a session |
| GET | `/api/flowdrop/pipelines/{pipeline_id}/interrupts` | List interrupts for a pipeline |

### Node Processors

| Plugin | Description |
|--------|-------------|
| `ConfirmationNode` | Creates a yes/no confirmation interrupt |
| `ChoiceNode` | Creates a choice selection interrupt |
| `TextInputNode` | Creates a free-text input interrupt |
| `FormInputNode` | Creates a JSON schema form interrupt |

## References

- [flowdrop_session](flowdrop_session.md) — session-aware interrupt handling
- [flowdrop_stategraph](flowdrop_stategraph.md) — approval gates use the interrupt system
- [flowdrop_pipeline](flowdrop_pipeline.md) — pipeline pause/resume mechanics
- [flowdrop_playground](flowdrop_playground.md) — interactive UI for resolving interrupts
