Summary

Workflows can pause and resume, but there's no declarative way to involve a human operator mid-workflow. An operator should be able to review outputs, approve/reject, provide input, or view artifacts (images, articles, data) — all through the channel they're already using (Telegram, email, dashboard).

Problem

Current workflows are fully autonomous. When a workflow generates an article, image, or decision that needs human validation, there's no way to:

1. Show the output to a human and wait for approval
2. Let a human provide corrections or additional input mid-flow
3. Route different review steps to different people
4. Set timeouts (auto-approve after N hours if no response)

The existing pause_run / resume_run mechanism is low-level (API-only, requires resume tokens). The approval system only covers skill workshop, not workflow steps.

Proposed: operator step mode

New StepMode variant

pub enum StepMode {
    Sequential,
    FanOut,
    Collect,
    Conditional { condition: String },
    Loop { until: String, max_iterations: usize },
    // NEW:
    Operator {
        /// Who to notify — channel + recipient (e.g., "telegram:@pakman", "email:[email protected]")
        notify: Vec<String>,
        /// What the operator can do
        actions: Vec<OperatorAction>,
        /// Auto-resolve after timeout (None = wait forever)
        timeout_secs: Option<u64>,
        /// What happens on timeout
        timeout_action: OperatorTimeoutAction,
    },
}

pub enum OperatorAction {
    Approve,          // approve the previous step's output
    Reject,           // reject and stop or retry
    Edit,             // provide corrections/edits
    FreeformInput,    // open-ended input from the operator
}

pub enum OperatorTimeoutAction {
    Approve,          // auto-approve on timeout
    Reject,           // auto-reject on timeout
    Pause,            // pause workflow (default)
}

Workflow TOML example

name = "publish_article"

[[steps]]
name = "research"
agent = "researcher"
prompt_template = "Research {{topic}} and produce a draft article"

[[steps]]
name = "review_draft"
mode.operator = {
    notify = ["telegram:@pakman"],
    actions = ["approve", "edit"],
    timeout_secs = 86400,
    timeout_action = "pause"
}
prompt_template = "Please review this article draft. Approve or suggest edits."

[[steps]]
name = "publish"
agent = "social-media"
prompt_template = "Publish the approved article to the blog"

How it works

1. Step N completes → output (article, image, data) is captured
2. Operator step begins → workflow pauses, notification sent via specified channel(s)
3. Operator receives: previous step's output + action buttons (Approve/Reject/Edit)
4. Operator responds: via channel reply (Telegram message, email reply, dashboard button)
5. Workflow resumes: operator's response becomes the step output, fed to the next step
6. Timeout: if configured, auto-resolves after N seconds

Channel integration

The notification uses the existing channel bridge infrastructure:

• Telegram: sends message with inline keyboard buttons (Approve/Reject) + the artifact
• Email: sends the artifact with reply instructions
• Dashboard: shows in the approvals panel with action buttons

The operator's response is routed back to the workflow via the existing channel_send → agent message path, but targeted at the workflow's pause handler instead of an agent session.

Integration with existing systems

Artifacts

Operator steps should be able to display rich content:

• Text (articles, reports)
• Images (generated images, charts)
• Files (PDFs, CSVs)
• Tables (structured data)

The channel adapter formats these appropriately per platform (Telegram photo + caption, email attachment, dashboard inline preview).

Before

Workflows are fire-and-forget. Human review requires stopping the workflow, manually checking output via API, then restarting.

After

Workflows can declaratively pause for human input at any step, notify the operator via their preferred channel, and resume with their response. Enables: editorial review, approval gates, interactive data collection, quality control.

Related

• pause_run / resume_run in workflow.rs — existing low-level mechanism
• /api/approvals — existing approval UI (to be extended)
• feat(workflows): allow steps to reference existing registry agents instead of spawning ephemeral children #4834 — workflow steps referencing existing agents
• Channel bridge infrastructure (crates/librefang-channels/src/bridge.rs)