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}