feat(hitl): add human in the loop block

[Sg312]

Summary

Adds approval (hitl) block

Type of Change

• New feature

Testing

Manual

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Preview	Comments	Updated (UTC)
docs	Skipped			Nov 6, 2025 11:56pm

[greptile-apps]

Greptile Overview

Greptile Summary

This PR implements a comprehensive human-in-the-loop (HITL) feature allowing workflows to pause execution and wait for human input before continuing. The implementation includes:

Core Changes:

• New pause_resume block handler that generates pause metadata and executes notification tools
• Execution engine modified to detect pause blocks and halt execution while serializing state
• PauseResumeManager class handling database persistence, queue management, and resume orchestration
• Snapshot serialization/restoration system to capture and restore full execution state

Database Schema:

• paused_executions table storing serialized snapshots, pause points, and metadata
• resume_queue table managing concurrent resume requests with status tracking
• Proper indexes on workflow_id, status, and execution_id for query performance

API & UI:

• Resume API endpoints at /api/resume/[workflowId]/[executionId]/[contextId] with POST (submit) and GET (status)
• React client UI (1463 lines) for dynamic form rendering and submission handling
• Notification tool execution for alerting users about pending approvals

DAG & Execution:

• Enhanced edge construction to wire pause trigger mappings correctly
• Resume execution removes edges from completed pause blocks to prevent re-execution
• Transaction-based concurrency control for queue management

Key Features:

• Support for both API and human operation modes
• Queue system prevents concurrent resumes on same execution
• Preserves loop and parallel execution context across pause/resume
• Self-reference capability allowing pause blocks to reference their own outputs

Confidence Score: 3/5

• This PR requires careful testing before merging due to race condition risks and fire-and-forget error handling
• The implementation is architecturally sound with proper database schema, snapshot serialization, and queue management. However, two critical issues lower confidence: (1) fire-and-forget pattern in resume API loses immediate errors, (2) missing row-level locking could allow race conditions in concurrent resume requests. The extensive changes across 90 files touch core execution logic which needs thorough testing.
• apps/sim/app/api/resume/[workflowId]/[executionId]/[contextId]/route.ts (error handling) and apps/sim/lib/workflows/executor/pause-resume-manager.ts (concurrency control)

Important Files Changed

File Analysis

Filename	Score	Overview
packages/db/schema.ts	5/5	Added two new tables (paused_executions and resume_queue) with proper foreign keys, indexes, and constraints for managing workflow pause/resume state
apps/sim/executor/handlers/pause-resume/pause-resume-handler.ts	4/5	Implements HITL block handler with notification tool execution, response data parsing, and pause metadata creation; extensive data normalization logic
apps/sim/lib/workflows/executor/pause-resume-manager.ts	3/5	Core pause/resume orchestration with database persistence, queue management, snapshot restoration, and resume execution; includes transaction-based concurrency control and edge removal logic for resumed blocks
apps/sim/executor/execution/engine.ts	4/5	Modified execution engine to detect pause metadata, halt execution when pauses occur, handle resume triggers, and build paused execution results with snapshot serialization
apps/sim/executor/execution/snapshot-serializer.ts	5/5	New file that serializes execution snapshots including DAG structure, state, and trigger IDs for pause persistence
apps/sim/executor/dag/construction/edges.ts	4/5	Enhanced edge construction to handle pause trigger mappings and wire resume trigger nodes correctly in the DAG
apps/sim/app/api/resume/[workflowId]/[executionId]/[contextId]/route.ts	4/5	API endpoint for resuming paused executions with queue management, validation, and async execution triggering; includes GET endpoint for pause context details
apps/sim/app/resume/[workflowId]/[executionId]/resume-page-client.tsx	4/5	Large React client component (1463 lines) providing UI for human-in-the-loop interactions with dynamic form rendering, status polling, and submission handling
apps/sim/executor/execution/block-executor.ts	4/5	Updated to prepare self-reference for pause/resume blocks, enabling blocks to reference their own outputs during input resolution

Sequence Diagram

sequenceDiagram
    participant Client
    participant API as Resume API
    participant Manager as PauseResumeManager
    participant DB as Database
    participant Engine as ExecutionEngine
    participant Handler as PauseResumeHandler

    Note over Client,Handler: Initial Workflow Execution
    Client->>Engine: Execute Workflow
    Engine->>Handler: Execute Pause Block
    Handler->>Handler: Generate pause metadata
    Handler-->>Engine: Return output with _pauseMetadata
    Engine->>Engine: Detect pause, halt execution
    Engine->>Manager: Serialize snapshot
    Manager->>DB: INSERT paused_executions
    Manager-->>Client: Return paused result with resume links

    Note over Client,Handler: Resume Request
    Client->>API: POST /resume/[workflowId]/[executionId]/[contextId]
    API->>Manager: enqueueOrStartResume()
    Manager->>DB: BEGIN TRANSACTION
    Manager->>DB: SELECT paused_execution
    Manager->>DB: Check pause_point.resumeStatus
    
    alt Active resume exists
        Manager->>DB: INSERT resume_queue (status=pending)
        Manager->>DB: Update pause_point (status=queued)
        Manager->>DB: COMMIT
        Manager-->>API: {status: queued, queuePosition: N}
        API-->>Client: Queued response
    else No active resume
        Manager->>DB: INSERT resume_queue (status=claimed)
        Manager->>DB: Update pause_point (status=resuming)
        Manager->>DB: COMMIT
        Manager-->>API: {status: starting, ...execution_data}
        API->>Manager: startResumeExecution() [fire-and-forget]
        API-->>Client: Started response
        
        Note over Manager,Engine: Resume Execution (Async)
        Manager->>DB: Load execution snapshot
        Manager->>Manager: Restore ExecutionSnapshot
        Manager->>Manager: Inject resume input into pause block output
        Manager->>Manager: Calculate edges to remove
        Manager->>Engine: Execute with restored snapshot
        Engine->>Engine: Process pending blocks
        
        alt Execution pauses again
            Engine-->>Manager: Paused result
            Manager->>DB: Persist new pause state
        else Execution completes
            Engine-->>Manager: Success result
            Manager->>DB: Update snapshot after resume
        end
        
        Manager->>DB: Mark resume_queue entry completed
        Manager->>Manager: processQueuedResumes()
        
        alt Queued resumes exist
            Manager->>DB: SELECT next pending resume
            Manager->>DB: UPDATE status=claimed
            Manager->>Manager: startResumeExecution() [recursive]
        end
    end

Loading

_{82 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}