Merge branch 'staging' into dev

Author: icecrasher321

.github/workflows/ci.yml

@@ -126,7 +126,7 @@ jobs:
             ecr_repo_secret: ECR_REALTIME
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Configure AWS credentials
         uses: aws-actions/configure-aws-credentials@v4
@@ -200,7 +200,7 @@ jobs:
   # Build ARM64 images for GHCR (main branch only, runs in parallel)
   build-ghcr-arm64:
     name: Build ARM64 (GHCR Only)
-    needs: [test-build, detect-version]
+    needs: [detect-version]
     runs-on: blacksmith-8vcpu-ubuntu-2404-arm
     if: github.event_name == 'push' && github.ref == 'refs/heads/main'
     permissions:
@@ -219,7 +219,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Login to GHCR
         uses: docker/login-action@v3
@@ -322,10 +322,10 @@ jobs:
     outputs:
       docs_changed: ${{ steps.filter.outputs.docs }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 2  # Need at least 2 commits to detect changes
-      - uses: dorny/paths-filter@v3
+      - uses: dorny/paths-filter@v4
         id: filter
         with:
           filters: |
@@ -352,7 +352,7 @@ jobs:
       contents: write
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
 

.github/workflows/docs-embeddings.yml

@@ -15,7 +15,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2

.github/workflows/i18n.yml

@@ -14,7 +14,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           ref: staging
           token: ${{ secrets.GH_PAT }}
@@ -115,7 +115,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           ref: staging
 

.github/workflows/images.yml

@@ -31,7 +31,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Configure AWS credentials
         uses: aws-actions/configure-aws-credentials@v4
@@ -117,7 +117,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Login to GHCR
         uses: docker/login-action@v3

.github/workflows/migrations.yml

@@ -14,7 +14,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2

.github/workflows/publish-cli.yml

@@ -14,7 +14,7 @@ jobs:
     runs-on: blacksmith-4vcpu-ubuntu-2404
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2

.github/workflows/publish-python-sdk.yml

@@ -14,7 +14,7 @@ jobs:
     runs-on: blacksmith-4vcpu-ubuntu-2404
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Setup Python
         uses: actions/setup-python@v5

.github/workflows/publish-ts-sdk.yml

@@ -14,7 +14,7 @@ jobs:
     runs-on: blacksmith-4vcpu-ubuntu-2404
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2

.github/workflows/test-build.yml

@@ -14,7 +14,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2

apps/docs/content/docs/en/blocks/human-in-the-loop.mdx

@@ -78,7 +78,7 @@ Defines the fields approvers fill in when responding. This data becomes availabl
 }
 ```
 
-Access resume data in downstream blocks using `<blockId.resumeInput.fieldName>`. 
+Access resume data in downstream blocks using `<blockId.fieldName>`. 
 
 ## Approval Methods
 
@@ -93,11 +93,12 @@ Access resume data in downstream blocks using `<blockId.resumeInput.fieldName>`.
   <Tab>
     ### REST API
 
-    Programmatically resume workflows using the resume endpoint. The `contextId` is available from the block's `resumeEndpoint` output or from the paused execution detail.
+    Programmatically resume workflows using the resume endpoint. The `contextId` is available from the block's `resumeEndpoint` output or from the `_resume` object in the paused execution response.
 
     ```bash
     POST /api/resume/{workflowId}/{executionId}/{contextId}
     Content-Type: application/json
+    X-API-Key: your-api-key
 
     {
       "input": {
@@ -107,23 +108,56 @@ Access resume data in downstream blocks using `<blockId.resumeInput.fieldName>`.
     }
     ```
 
-    The response includes a new `executionId` for the resumed execution:
+    The resume endpoint automatically respects the execution mode used in the original execute call:
+    
+    - **Sync mode** (default) — The response waits for the remaining workflow to complete and returns the full result:
+    
+    ```json
+    {
+      "success": true,
+      "status": "completed",
+      "executionId": "<resumeExecutionId>",
+      "output": { ... },
+      "metadata": { "duration": 1234, "startTime": "...", "endTime": "..." }
+    }
+    ```
+    
+    If the resumed workflow hits another HITL block, the response returns `"status": "paused"` with new `_resume` URLs in the output.
+    
+    - **Stream mode** (`stream: true` on the original execute call) — The resume response streams SSE events with `selectedOutputs` chunks, just like the initial execution.
+    
+    - **Async mode** (`X-Execution-Mode: async` on the original execute call) — The resume dispatches execution to a background worker and returns immediately with `202`, including a `jobId` and `statusUrl` for polling:
 
     ```json
     {
-      "status": "started",
+      "success": true,
+      "async": true,
+      "jobId": "<jobId>",
       "executionId": "<resumeExecutionId>",
-      "message": "Resume execution started."
+      "message": "Resume execution queued",
+      "statusUrl": "/api/jobs/<jobId>"
     }
     ```
 
-    To poll execution progress after resuming, connect to the SSE stream:
+    #### Polling execution status
+    
+    Poll the `statusUrl` from the async response to check when the resume completes:
 
     ```bash
-    GET /api/workflows/{workflowId}/executions/{resumeExecutionId}/stream
+    GET /api/jobs/{jobId}
+    X-API-Key: your-api-key
     ```
 
-    Build custom approval UIs or integrate with existing systems.
+    Returns job status and, when completed, the full workflow output.
+    
+    To check on a paused execution's pause points and resume links:
+    
+    ```bash
+    GET /api/resume/{workflowId}/{executionId}
+    X-API-Key: your-api-key
+    ```
+    
+    Returns the paused execution detail with all pause points, their statuses, and resume links. Returns `404` when the execution has completed and is no longer paused.
   </Tab>
   <Tab>
     ### Webhook
@@ -132,6 +166,53 @@ Access resume data in downstream blocks using `<blockId.resumeInput.fieldName>`.
   </Tab>
 </Tabs>
 
+## API Execute Behavior
+
+When triggering a workflow via the execute API (`POST /api/workflows/{id}/execute`), HITL blocks cause the execution to pause and return the `_resume` data in the response:
+
+<Tabs items={['Sync (JSON)', 'Stream (SSE)', 'Async']}>
+  <Tab>
+    The response includes the full pause data with resume URLs:
+    
+    ```json
+    {
+      "success": true,
+      "executionId": "<executionId>",
+      "output": {
+        "data": {
+          "operation": "human",
+          "_resume": {
+            "apiUrl": "/api/resume/{workflowId}/{executionId}/{contextId}",
+            "uiUrl": "/resume/{workflowId}/{executionId}",
+            "contextId": "<contextId>",
+            "executionId": "<executionId>",
+            "workflowId": "<workflowId>"
+          }
+        }
+      }
+    }
+    ```
+  </Tab>
+  <Tab>
+    Blocks before the HITL stream their `selectedOutputs` normally. When execution pauses, the final SSE event includes `status: "paused"` and the `_resume` data:
+    
+    ```
+    data: {"blockId":"agent1","chunk":"streamed content..."}
+    data: {"event":"final","data":{"success":true,"output":{...,"_resume":{...}},"status":"paused"}}
+    data: "[DONE]"
+    ```
+    
+    On resume, blocks after the HITL stream their `selectedOutputs` the same way.
+    
+    <Callout type="info">
+      HITL blocks are automatically excluded from the `selectedOutputs` dropdown since their data is always included in the pause response.
+    </Callout>
+  </Tab>
+  <Tab>
+    Returns `202` immediately. Use the polling endpoint to check when the execution pauses.
+  </Tab>
+</Tabs>
+
 ## Common Use Cases
 
 **Content Approval** - Review AI-generated content before publishing
@@ -161,9 +242,9 @@ Agent (Generate) → Human in the Loop (QA) → Gmail (Send)
 **`response`** - Display data shown to the approver (json)
 **`submission`** - Form submission data from the approver (json)
 **`submittedAt`** - ISO timestamp when the workflow was resumed
-**`resumeInput.*`** - All fields defined in Resume Form become available after the workflow resumes
+**`<fieldName>`** - All fields defined in Resume Form become available at the top level after the workflow resumes
 
-Access using `<blockId.resumeInput.fieldName>`.
+Access using `<blockId.fieldName>`.
 
 ## Example
 
@@ -187,7 +268,7 @@ Access using `<blockId.resumeInput.fieldName>`.
 **Downstream Usage:**
 ```javascript
 // Condition block
-<approval1.resumeInput.approved> === true
+<approval1.approved> === true
 ```
 The example below shows an approval portal as seen by an approver after the workflow is paused. Approvers can review the data and provide inputs as a part of the workflow resumption. The approval portal can be accessed directly via the unique URL, `<blockId.url>`.
 
@@ -204,7 +285,7 @@ The example below shows an approval portal as seen by an approver after the work
 <FAQ items={[
   { question: "How long does the workflow stay paused?", answer: "The workflow pauses indefinitely until a human provides input through the approval portal, the REST API, or a webhook. There is no automatic timeout — it will wait until someone responds." },
   { question: "What notification channels can I use to alert approvers?", answer: "You can configure notifications through Slack, Gmail, Microsoft Teams, SMS (via Twilio), or custom webhooks. Include the approval URL in your notification message so approvers can access the portal directly." },
-  { question: "How do I access the approver's input in downstream blocks?", answer: "Use the syntax <blockId.resumeInput.fieldName> to reference specific fields from the resume form. For example, if your block ID is 'approval1' and the form has an 'approved' field, use <approval1.resumeInput.approved>." },
+  { question: "How do I access the approver's input in downstream blocks?", answer: "Use the syntax <blockId.fieldName> to reference specific fields from the resume form. For example, if your block name is 'approval1' and the form has an 'approved' field, use <approval1.approved>." },
   { question: "Can I chain multiple Human in the Loop blocks for multi-stage approvals?", answer: "Yes. You can place multiple Human in the Loop blocks in sequence to create multi-stage approval workflows. Each block pauses independently and can have its own notification configuration and resume form fields." },
   { question: "Can I resume the workflow programmatically without the portal?", answer: "Yes. Each block exposes a resume API endpoint that you can call with a POST request containing the form data as JSON. This lets you build custom approval UIs or integrate with existing systems like Jira or ServiceNow." },
   { question: "What outputs are available after the workflow resumes?", answer: "The block outputs include the approval portal URL, the resume API endpoint URL, the display data shown to the approver, the form submission data, the raw resume input, and an ISO timestamp of when the workflow was resumed." },