Human in the Loop

# Overview

This project focused on enabling Human in the Loop workflows in BuildShip by leveraging the platform’s existing pause and resume execution model. The goal was to let workflows safely wait for human input without breaking automation, consuming credits, or requiring complex workarounds.

The result was two production nodes:

• Email Human in the Loop: Delivers approval requests and input forms directly to user inboxes with dynamic resume links.
• Slack Human in the Loop: Dispatches interactive message blocks into Slack channels or DMs with live response validation.

Both allow workflows to pause, request a decision or structured input from a human, and then resume execution once a response is received.

# The Problem

Many real-world workflows cannot be fully automated:

• AI outputs need human review and validation.
• Critical operations and financial actions require explicit sign-off.
• Contextual and subjective decisions need domain expertise.

Before this work, users had to either stop automation entirely or build fragile external approval systems.

The requirements were clear:

• Allow workflows to pause safely for human input.
• Resume cleanly with validated, type-safe data.
• Keep the entire authoring experience native to BuildShip.

# Leveraging Pause and Resume

BuildShip already supports pausing workflows using an underlying pause and resume mechanism. My work focused on applying this capability to real communication channels and designing a clean developer experience around it.

When a Human in the Loop node executes, it calls pause and returns a waiting response. The workflow state is preserved, and a unique resume URL is generated. Execution stops until that URL is invoked.

This approach avoids long-running execution, polling, or credit usage while waiting. From the workflow author’s perspective, it feels like a natural pause in the flow.

# Response Models

Both Email and Slack nodes support two distinct response models:

• Conditional responses: Simple approvals or rejections. Authors can customize button labels, and the node returns a clean boolean result back into the workflow graph.
• Structured responses: Allow workflow authors to define a JSON Schema describing expected input. Human responses are validated against this schema before the workflow resumes, ensuring downstream nodes receive predictable, typed data.

This made it possible to collect real structured input from humans instead of unvalidated free-form text.

# Email Human in the Loop

The Email HITL node delivers approval or input requests via email.

When the node runs, it calls an internal workflow responsible for sending the email. That workflow handles authentication, template rendering, and attachments. After triggering the email, the main workflow pauses.

Emails include links or buttons wired directly to the resume URL. When a recipient responds, the workflow resumes and processes the result.

The implementation supports rich HTML templates, placeholder interpolation, and image handling. Images can be external URLs or files that are automatically converted and uploaded to make them publicly accessible.

This allowed email-based approvals without requiring users to build separate email infrastructure.

# Slack Human in the Loop

The Slack HITL node integrates with Slack using OAuth and delivers requests directly into channels or direct messages.

When executed, the node sends a Slack message built from dynamic blocks and then pauses the workflow. Message metadata and resume details are stored in Firestore to preserve state across the pause.

When a user interacts with the message, the input handler retrieves the stored context, validates the response, updates the Slack message to mark it as completed, and resumes the workflow.

This avoids duplicate responses and gives clear visual feedback inside Slack.

# State Management and Validation

Slack-based HITL requires explicit state management. Message timestamps, channel IDs, response schemas, and callback URLs are persisted so the workflow can safely resume later.

• Structured responses are validated against the original JSON Schema before continuing execution.
• Conditional responses are passed through directly as boolean decisions.

This ensures that human input does not introduce inconsistent or malformed data into downstream workflow nodes.

# Developer Experience

A large part of this work focused on DX rather than raw functionality:

• Workflow authors can configure HITL nodes without thinking about low-level callbacks or database storage.
• Templates support placeholder interpolation and separate states for pending and resolved requests.
• Errors are surfaced clearly when workflows are not in a shippable state or when integrations are misconfigured.
• The pause itself does not consume runtime credits, making long-running human approvals practical.