fix(api): close v2 resume and log gaps

Author: TheodoreSpeaks

apps/docs/openapi-v2-logs.json

@@ -36,7 +36,7 @@
       "get": {
         "operationId": "listLogs",
         "summary": "List Logs",
-        "description": "List workflow execution logs for a workspace with filtering and opaque cursor pagination. Returns `{ data, nextCursor }`. By default (`details=basic`) each entry contains summary fields only; pass `details=full` to include the per-execution `workflow` summary, and additionally `includeFinalOutput=true` / `includeTraceSpans=true` to materialize `finalOutput` / `traceSpans` on each entry.",
+        "description": "List workflow execution logs for a workspace with filtering and opaque cursor pagination. Returns `{ data, nextCursor }`. By default (`details=basic`) each entry contains summary fields only. Pass `details=full` to include the per-execution `workflow` summary. Requesting `includeFinalOutput=true` or `includeTraceSpans=true` automatically enables full detail and materializes the requested field.",
         "tags": ["Logs"],
         "x-codeSamples": [
           {
@@ -158,7 +158,7 @@
           {
             "name": "details",
             "in": "query",
-            "description": "Response detail level. basic returns summary fields only. full additionally includes the per-entry workflow summary and enables the includeFinalOutput / includeTraceSpans materialization flags.",
+            "description": "Response detail level. basic returns summary fields only. full additionally includes the per-entry workflow summary. Requesting includeFinalOutput or includeTraceSpans also enables full detail.",
             "schema": {
               "type": "string",
               "enum": ["basic", "full"],
@@ -168,7 +168,7 @@
           {
             "name": "includeTraceSpans",
             "in": "query",
-            "description": "When true, includes block-level execution trace spans on each entry. Only applies when details=full.",
+            "description": "When true, includes block-level execution trace spans on each entry and automatically enables full detail.",
             "schema": {
               "type": "boolean",
               "default": false
@@ -177,7 +177,7 @@
           {
             "name": "includeFinalOutput",
             "in": "query",
-            "description": "When true, includes the workflow's final output on each entry. Only applies when details=full.",
+            "description": "When true, includes the workflow's final output on each entry and automatically enables full detail.",
             "schema": {
               "type": "boolean",
               "default": false
@@ -455,6 +455,56 @@
           }
         }
       },
+      "TraceSpan": {
+        "type": "object",
+        "additionalProperties": true,
+        "description": "A block, model, tool, or workflow trace span with timing, cost, and failure metadata.",
+        "required": ["id", "name", "type"],
+        "properties": {
+          "id": { "type": "string" },
+          "name": { "type": "string" },
+          "type": { "type": "string" },
+          "duration": { "type": "number" },
+          "durationMs": { "type": "number" },
+          "startTime": { "type": "string" },
+          "endTime": { "type": "string" },
+          "status": { "type": "string" },
+          "errorHandled": {
+            "type": "boolean",
+            "description": "Whether an error handler path handled this span's failure."
+          },
+          "errorType": {
+            "type": "string",
+            "description": "Structured failure class such as RateLimitError."
+          },
+          "errorMessage": {
+            "type": "string",
+            "description": "Human-readable failure message."
+          },
+          "blockId": { "type": "string" },
+          "input": {},
+          "output": {},
+          "tokens": {},
+          "cost": {
+            "type": "object",
+            "properties": {
+              "total": { "type": "number" },
+              "input": { "type": "number" },
+              "output": { "type": "number" },
+              "toolCost": { "type": "number" }
+            }
+          },
+          "relativeStartMs": { "type": "number" },
+          "toolCalls": {
+            "type": "array",
+            "items": { "type": "object", "additionalProperties": true }
+          },
+          "children": {
+            "type": "array",
+            "items": { "$ref": "#/components/schemas/TraceSpan" }
+          }
+        }
+      },
       "LogWorkflowSummary": {
         "type": "object",
         "description": "Workflow summary captured at execution time. Present on a list entry only when details=full.",
@@ -632,14 +682,13 @@
           "finalOutput": {
             "type": "object",
             "additionalProperties": true,
-            "description": "The workflow's final output. The shape depends on the workflow. Present only when details=full and includeFinalOutput=true."
+            "description": "The workflow's final output. The shape depends on the workflow. Present when includeFinalOutput=true; requesting it automatically enables full detail."
           },
           "traceSpans": {
             "type": "array",
-            "description": "Block-level execution trace spans with timing, inputs, and outputs. Present only when details=full and includeTraceSpans=true.",
+            "description": "Block-level execution trace spans with timing, cost, and failure metadata. Present when includeTraceSpans=true; requesting it automatically enables full detail.",
             "items": {
-              "type": "object",
-              "additionalProperties": true
+              "$ref": "#/components/schemas/TraceSpan"
             }
           }
         }
@@ -730,10 +779,9 @@
           },
           "traceSpans": {
             "type": "array",
-            "description": "Materialized block-level execution trace spans with timing, inputs, and outputs. Empty when the run has no spans.",
+            "description": "Materialized block-level execution trace spans with timing, cost, and failure metadata. Empty when the run has no spans.",
             "items": {
-              "type": "object",
-              "additionalProperties": true
+              "$ref": "#/components/schemas/TraceSpan"
             }
           },
           "finalOutput": {

apps/docs/openapi-v2-workflows.json

@@ -1607,7 +1607,32 @@
                         },
                         "paused": {
                           "type": ["object", "null"],
-                          "description": "Pause detail for human-in-the-loop runs."
+                          "description": "Pause detail for human-in-the-loop runs, including the context ID required by the resume endpoint.",
+                          "required": [
+                            "contextId",
+                            "pausedAt",
+                            "resumeAt",
+                            "pauseKind",
+                            "blockedOnBlockId",
+                            "automaticResumeWaitingReason",
+                            "pausedExecutionId",
+                            "pausePointCount",
+                            "resumedCount"
+                          ],
+                          "properties": {
+                            "contextId": { "type": "string" },
+                            "pausedAt": { "type": "string" },
+                            "resumeAt": { "type": ["string", "null"] },
+                            "pauseKind": {
+                              "type": ["string", "null"],
+                              "enum": ["time", "human", null]
+                            },
+                            "blockedOnBlockId": { "type": ["string", "null"] },
+                            "automaticResumeWaitingReason": { "type": ["string", "null"] },
+                            "pausedExecutionId": { "type": "string" },
+                            "pausePointCount": { "type": "number" },
+                            "resumedCount": { "type": "number" }
+                          }
                         },
                         "cost": {
                           "type": ["object", "null"],
@@ -1683,7 +1708,7 @@
       "post": {
         "operationId": "resumeWorkflowExecutionV2",
         "summary": "Resume a workflow execution",
-        "description": "Resumes one human-in-the-loop pause context on the parent execution. The resumed attempt receives a new execution ID. Sync attempts return the execution resource, stream attempts return Server-Sent Events, and async or serialized attempts return a 202 receipt whose `statusUrl` is the v2 execution resource.",
+        "description": "Resumes one human-in-the-loop pause context on the parent execution. Responses are always JSON and the resumed attempt receives a new execution ID. Sync attempts return the execution resource. Async, serialized, and inherited stream-mode attempts return a 202 receipt whose `statusUrl` is the v2 execution resource.",
         "tags": ["Workflows"],
         "security": [
           {

apps/sim/app/api/resume/[workflowId]/[executionId]/[contextId]/route.test.ts

@@ -322,6 +322,48 @@ describe('POST /api/resume/[workflowId]/[executionId]/[contextId]', () => {
     )
   })
 
+  it('queues inherited stream-mode resumes when the caller requires JSON', async () => {
+    mockGetPausedExecutionDetail.mockResolvedValueOnce(
+      createPausedExecution({ executionMode: 'stream' })
+    )
+    mockEnqueueOrStartResume.mockResolvedValueOnce({
+      status: 'started',
+      resumeExecutionId: 'resume-execution-1',
+      resumeEntryId: 'resume-entry-1',
+      pausedExecution: { id: 'paused-execution-1' },
+      contextId: CONTEXT_ID,
+      resumeInput: { approved: true },
+      userId: 'current-api-key-user',
+    })
+    const { request } = makeRequest()
+
+    const response = await handleResumeExecution({
+      request,
+      workflowId: WORKFLOW_ID,
+      executionId: EXECUTION_ID,
+      contextId: CONTEXT_ID,
+      workspaceId: WORKSPACE_ID,
+      userId: 'current-api-key-user',
+      resumeInput: { approved: true },
+      isApiCaller: true,
+      pollingSurface: 'v2',
+      allowStreaming: false,
+    })
+
+    expect(response.status).toBe(202)
+    expect(response.headers.get('Content-Type')).toContain('application/json')
+    await expect(response.json()).resolves.toMatchObject({
+      async: true,
+      executionId: 'resume-execution-1',
+      statusUrl: 'https://test.sim.ai/api/v2/workflows/workflow-1/executions/resume-execution-1',
+    })
+    expect(mockEnqueueResume).toHaveBeenCalledWith(
+      'resume-execution',
+      expect.objectContaining({ resumeExecutionId: 'resume-execution-1' }),
+      expect.objectContaining({ jobId: 'resume-execution:resume-entry-1' })
+    )
+  })
+
   it.each([
     { statusCode: 402, message: 'Member usage limit reached', retryable: false },
     { statusCode: 429, message: 'Target concurrency full', retryable: true },

apps/sim/app/api/resume/resume-handler.ts

@@ -52,6 +52,8 @@ interface HandleResumeExecutionOptions {
   resumeInput: unknown
   isApiCaller: boolean
   pollingSurface: 'legacy' | 'v2'
+  /** When false, inherited stream-mode resumes use async JSON polling instead of SSE. */
+  allowStreaming?: boolean
 }
 
 function loadPausedExecutionSnapshot(
@@ -114,6 +116,7 @@ export async function handleResumeExecution({
   resumeInput,
   isApiCaller,
   pollingSurface,
+  allowStreaming = true,
 }: HandleResumeExecutionOptions): Promise<NextResponse> {
   const requestId = generateRequestId()
   const pausedExecution = await PauseResumeManager.getPausedExecutionDetail({
@@ -224,8 +227,11 @@ export async function handleResumeExecution({
       userId: enqueueResult.userId,
     }
 
+    const persistedExecutionMode = persistedSnapshot.metadata.executionMode ?? 'sync'
     const executionMode = isApiCaller
-      ? (persistedSnapshot.metadata.executionMode ?? 'sync')
+      ? persistedExecutionMode === 'stream' && !allowStreaming
+        ? 'async'
+        : persistedExecutionMode
       : undefined
     const includeThinking = persistedSnapshot.metadata.includeThinking === true
     const includeToolCalls = persistedSnapshot.metadata.includeToolCalls === true

apps/sim/app/api/v2/logs/route.test.ts

@@ -0,0 +1,109 @@
+/**
+ * @vitest-environment node
+ */
+import { NextRequest } from 'next/server'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const {
+  mockCheckRateLimit,
+  mockResolveWorkspaceAccess,
+  mockListPublicWorkflowLogs,
+  mockMaterializeExecutionData,
+} = vi.hoisted(() => ({
+  mockCheckRateLimit: vi.fn(),
+  mockResolveWorkspaceAccess: vi.fn(),
+  mockListPublicWorkflowLogs: vi.fn(),
+  mockMaterializeExecutionData: vi.fn(),
+}))
+
+vi.mock('@/app/api/v1/middleware', () => ({
+  checkRateLimit: mockCheckRateLimit,
+  resolveWorkspaceAccess: mockResolveWorkspaceAccess,
+}))
+
+vi.mock('@/app/api/v2/lib/gate', () => ({
+  v2ApiGateError: vi.fn().mockResolvedValue(null),
+}))
+
+vi.mock('@/lib/logs/public-queries', () => ({
+  decodePublicLogCursor: vi.fn(),
+  listPublicWorkflowLogs: mockListPublicWorkflowLogs,
+}))
+
+vi.mock('@/lib/logs/execution/trace-store', () => ({
+  materializeExecutionData: mockMaterializeExecutionData,
+}))
+
+import { GET } from '@/app/api/v2/logs/route'
+
+const WORKSPACE_ID = '6fc7631d-88cd-46f8-9f0a-d4764daef7f8'
+const RATE_LIMIT_OK = {
+  allowed: true,
+  userId: 'user-1',
+  keyType: 'workspace',
+  limit: 100,
+  remaining: 99,
+  resetAt: new Date('2026-08-06T01:00:00.000Z'),
+}
+const LOG_ROW = {
+  executionId: 'execution-1',
+  workflowId: 'workflow-1',
+  workspaceId: WORKSPACE_ID,
+  deploymentVersionId: null,
+  status: 'completed',
+  level: 'info',
+  trigger: 'api',
+  startedAt: new Date('2026-08-06T00:00:00.000Z'),
+  endedAt: new Date('2026-08-06T00:00:01.000Z'),
+  totalDurationMs: 1000,
+  costTotal: null,
+  files: null,
+  executionData: { stored: true },
+  workflowName: 'Support Agent',
+  workflowDescription: null,
+  workflowArchivedAt: null,
+}
+
+function callLogs(query: string) {
+  return GET(
+    new NextRequest(`http://localhost:3000/api/v2/logs?workspaceId=${WORKSPACE_ID}&${query}`)
+  )
+}
+
+describe('GET /api/v2/logs materialized fields', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockCheckRateLimit.mockResolvedValue(RATE_LIMIT_OK)
+    mockResolveWorkspaceAccess.mockResolvedValue(null)
+    mockListPublicWorkflowLogs.mockResolvedValue({ data: [LOG_ROW], nextCursor: null })
+  })
+
+  it.each([false, 0, ''])('preserves a requested falsy final output: %j', async (finalOutput) => {
+    mockMaterializeExecutionData.mockResolvedValue({ finalOutput })
+
+    const response = await callLogs('includeFinalOutput=true')
+    const body = await response.json()
+
+    expect(response.status).toBe(200)
+    expect(body.data[0].finalOutput).toBe(finalOutput)
+    expect(body.data[0].workflow).toMatchObject({ name: 'Support Agent' })
+    expect(mockListPublicWorkflowLogs).toHaveBeenCalledWith(
+      expect.objectContaining({ includeExecutionData: true })
+    )
+  })
+
+  it('makes includeTraceSpans imply full detail', async () => {
+    const traceSpans = [{ id: 'span-1', name: 'Agent', type: 'agent' }]
+    mockMaterializeExecutionData.mockResolvedValue({ traceSpans })
+
+    const response = await callLogs('includeTraceSpans=true')
+    const body = await response.json()
+
+    expect(response.status).toBe(200)
+    expect(body.data[0].traceSpans).toEqual(traceSpans)
+    expect(body.data[0].workflow).toMatchObject({ name: 'Support Agent' })
+    expect(mockListPublicWorkflowLogs).toHaveBeenCalledWith(
+      expect.objectContaining({ includeExecutionData: true })
+    )
+  })
+})