Make async tool resume delivery recoverable

Author: Sg312

apps/sim/app/api/workflows/[id]/execute/route.async.test.ts

@@ -852,8 +852,13 @@ describe('workflow execute async route', () => {
         status: 'pending',
       },
       { id: 'copilot-run-1', userId: 'session-user-1', workflowId: 'workflow-1' },
+      403,
+      'COPILOT_WORKFLOW_TOOL_BINDING_AWAITING_APPROVAL',
     ],
     [
+      // A finished call is a benign duplicate, not a defect: some other runner
+      // already owns this tool call, so it reports the same conflict the
+      // execution claim does and the client stays silent.
       'terminal tool row',
       {
         toolCallId: 'copilot-tool-1',
@@ -863,6 +868,8 @@ describe('workflow execute async route', () => {
         status: 'completed',
       },
       { id: 'copilot-run-1', userId: 'session-user-1', workflowId: 'workflow-1' },
+      409,
+      'COPILOT_WORKFLOW_EXECUTION_CONFLICT',
     ],
     [
       'different workflow target',
@@ -874,6 +881,8 @@ describe('workflow execute async route', () => {
         status: 'running',
       },
       { id: 'copilot-run-1', userId: 'session-user-1', workflowId: 'workflow-1' },
+      403,
+      'COPILOT_WORKFLOW_TOOL_BINDING_WORKFLOW_MISMATCH',
     ],
     [
       'different execution actor',
@@ -885,19 +894,28 @@ describe('workflow execute async route', () => {
         status: 'running',
       },
       { id: 'copilot-run-1', userId: 'other-user', workflowId: 'workflow-1' },
+      403,
+      'COPILOT_WORKFLOW_TOOL_BINDING_FOREIGN_OWNER',
     ],
-  ])('rejects a Copilot binding owned by a %s', async (_caseName, toolCall, run) => {
-    mockGetAsyncToolCall.mockResolvedValueOnce(toolCall)
-    mockGetRunSegment.mockResolvedValueOnce(run)
+    ['missing tool row', null, null, 404, 'COPILOT_WORKFLOW_TOOL_BINDING_UNKNOWN'],
+  ])(
+    'rejects a Copilot binding owned by a %s',
+    async (_caseName, toolCall, run, expectedStatus, expectedCode) => {
+      mockGetAsyncToolCall.mockResolvedValueOnce(toolCall)
+      mockGetRunSegment.mockResolvedValueOnce(run)
 
-    const response = await POST(createBoundCopilotExecutionRequest(), {
-      params: Promise.resolve({ id: 'workflow-1' }),
-    })
+      const response = await POST(createBoundCopilotExecutionRequest(), {
+        params: Promise.resolve({ id: 'workflow-1' }),
+      })
 
-    expect(response.status).toBe(403)
-    expect(mockExecuteWorkflowCore).not.toHaveBeenCalled()
-    expect(loggingSessionMockFns.mockSetTrustedExecutionCorrelation).not.toHaveBeenCalled()
-  })
+      expect(response.status).toBe(expectedStatus)
+      // The reason must be machine-readable — an opaque 403 is what stopped the
+      // client telling a benign duplicate from a real failure.
+      await expect(response.json()).resolves.toMatchObject({ code: expectedCode })
+      expect(mockExecuteWorkflowCore).not.toHaveBeenCalled()
+      expect(loggingSessionMockFns.mockSetTrustedExecutionCorrelation).not.toHaveBeenCalled()
+    }
+  )
 
   it('rejects Copilot workflow bindings outside the interactive SSE surface', async () => {
     const response = await POST(createBoundCopilotExecutionRequest({ stream: false }), {

apps/sim/app/api/workflows/[id]/execute/route.ts

@@ -21,18 +21,19 @@ import {
   type BillingAttributionSnapshot,
   requireBillingAttributionHeader,
 } from '@/lib/billing/core/billing-attribution'
-import { isWorkflowToolExecutionClaimable } from '@/lib/copilot/async-runs/lifecycle'
 import {
   claimWorkflowToolExecution,
   getAsyncToolCall,
   getRunSegment,
   releaseWorkflowToolExecutionClaim,
 } from '@/lib/copilot/async-runs/repository'
 import { COPILOT_WORKFLOW_EXECUTION_CONFLICT_CODE } from '@/lib/copilot/constants'
+import { CopilotDegradedReason } from '@/lib/copilot/generated/trace-attribute-values-v1'
+import { recordDegraded } from '@/lib/copilot/request/metrics'
 import {
   ASYNC_WORKFLOW_DEPLOYMENT_ERRORS,
-  isWorkflowToolName,
-  resolveWorkflowToolTargetId,
+  type CopilotWorkflowToolBindingResult,
+  classifyWorkflowToolBinding,
 } from '@/lib/copilot/tools/workflow-tools'
 import { admissionRejectedResponse, tryAdmit } from '@/lib/core/admission/gate'
 import {
@@ -168,25 +169,19 @@ const SERVER_EXECUTION_ID_CLAIM_ATTEMPTS = 3
 export const runtime = 'nodejs'
 export const dynamic = 'force-dynamic'
 
-async function isValidCopilotWorkflowToolBinding(params: {
+async function resolveCopilotWorkflowToolBinding(params: {
   toolCallId: string
   userId: string
   workflowId: string
-}): Promise<boolean> {
+}): Promise<CopilotWorkflowToolBindingResult> {
   const toolCall = await getAsyncToolCall(params.toolCallId)
-  if (
-    !toolCall ||
-    !isWorkflowToolName(toolCall.toolName) ||
-    !isWorkflowToolExecutionClaimable(toolCall.status, toolCall.permissionDecision)
-  ) {
-    return false
-  }
-
-  const run = await getRunSegment(toolCall.runId)
-  return (
-    run?.userId === params.userId &&
-    resolveWorkflowToolTargetId(toolCall.args, run.workflowId) === params.workflowId
-  )
+  const run = toolCall ? await getRunSegment(toolCall.runId) : null
+  return classifyWorkflowToolBinding({
+    toolCall,
+    run,
+    userId: params.userId,
+    workflowId: params.workflowId,
+  })
 }
 
 function createExecutionJsonResponse(
@@ -1019,18 +1014,29 @@ async function handleExecutePost(
       )
     }
 
-    if (
-      copilotToolCallId &&
-      !(await isValidCopilotWorkflowToolBinding({
+    if (copilotToolCallId) {
+      const binding = await resolveCopilotWorkflowToolBinding({
         toolCallId: copilotToolCallId,
         userId,
         workflowId,
-      }))
-    ) {
-      return NextResponse.json(
-        { error: 'Copilot workflow tool binding was not found' },
-        { status: 403 }
-      )
+      })
+      if (!binding.ok) {
+        // This rejection happens before any LoggingSession exists, so it leaves
+        // no execution log and no workflow span — log the reason or it is
+        // invisible everywhere except the browser console.
+        // This rejection happens before a LoggingSession or any workflow span
+        // exists, so the counter is the only place it becomes visible.
+        recordDegraded(CopilotDegradedReason.BindingRejected)
+        reqLogger.warn('Rejected Copilot workflow tool execution', {
+          copilotToolCallId,
+          workflowId,
+          reason: binding.rejection.code,
+        })
+        return NextResponse.json(
+          { error: binding.rejection.message, code: binding.rejection.code },
+          { status: binding.rejection.statusCode }
+        )
+      }
     }
 
     if (inputFromExecutionId) {

apps/sim/app/workspace/[workspaceId]/w/[workflowId]/utils/workflow-execution-utils.ts

@@ -1070,7 +1070,10 @@ export async function executeWorkflowWithFullLogging(
       error: errorMessage,
       httpStatus: response.status,
     })
-    throw new Error(errorMessage)
+    // Keep the status and code on the thrown error. Downgrading to a bare Error
+    // discarded both, so callers could not tell a Copilot binding rejection from
+    // any other 4xx — and the reason never reached the agent that could fix it.
+    throw new ExecutionStreamHttpError(errorMessage, response.status, errorCode)
   }
 
   if (!response.body) {

apps/sim/lib/copilot/generated/metrics-v1.ts

@@ -19,6 +19,7 @@ export const Metric = {
   CopilotCacheWrite: 'copilot.cache.write',
   CopilotChatBlobBytes: 'copilot.chat.blob.bytes',
   CopilotChatBlobCount: 'copilot.chat.blob.count',
+  CopilotDegradedCount: 'copilot.degraded.count',
   CopilotFileReadDuration: 'copilot.file.read.duration',
   CopilotFileReadSize: 'copilot.file.read.size',
   CopilotMessagesSerializeDuration: 'copilot.messages.serialize.duration',
@@ -48,6 +49,7 @@ export const MetricValues: readonly MetricValue[] = [
   'copilot.cache.write',
   'copilot.chat.blob.bytes',
   'copilot.chat.blob.count',
+  'copilot.degraded.count',
   'copilot.file.read.duration',
   'copilot.file.read.size',
   'copilot.messages.serialize.duration',

apps/sim/lib/copilot/generated/tool-catalog-v1.ts

@@ -4268,14 +4268,14 @@ export const RunBlock: ToolCatalogEntry = {
       workflowId: {
         type: 'string',
         description:
-          'Optional workflow ID to run. If not provided, uses the current workflow in context.',
+          'ID of the workflow to run. Always pass this explicitly — outside a workflow-scoped chat there is no current workflow to fall back to, and the run is rejected without it.',
       },
       workflow_input: {
         type: 'object',
         description: 'JSON object with key-value mappings where each key is an input field name',
       },
     },
-    required: ['blockId'],
+    required: ['workflowId', 'blockId'],
   },
   clientExecutable: true,
 }
@@ -4396,14 +4396,14 @@ export const RunFromBlock: ToolCatalogEntry = {
       workflowId: {
         type: 'string',
         description:
-          'Optional workflow ID to run. If not provided, uses the current workflow in context.',
+          'ID of the workflow to run. Always pass this explicitly — outside a workflow-scoped chat there is no current workflow to fall back to, and the run is rejected without it.',
       },
       workflow_input: {
         type: 'object',
         description: 'JSON object with key-value mappings where each key is an input field name',
       },
     },
-    required: ['startBlockId'],
+    required: ['workflowId', 'startBlockId'],
   },
   clientExecutable: true,
 }
@@ -4444,14 +4444,15 @@ export const RunWorkflow: ToolCatalogEntry = {
       workflowId: {
         type: 'string',
         description:
-          'Optional workflow ID to run. If not provided, uses the current workflow in context.',
+          'ID of the workflow to run. Always pass this explicitly — outside a workflow-scoped chat there is no current workflow to fall back to, and the run is rejected without it.',
       },
       workflow_input: {
         type: 'object',
         description:
           "JSON object matching the target trigger's inputSchema (from get_workflow_run_options). For external/webhook triggers this is the event payload; for API/Input triggers it is the form fields.",
       },
     },
+    required: ['workflowId'],
   },
   clientExecutable: true,
   requiresApproval: true,
@@ -4492,15 +4493,15 @@ export const RunWorkflowUntilBlock: ToolCatalogEntry = {
       workflowId: {
         type: 'string',
         description:
-          'Optional workflow ID to run. If not provided, uses the current workflow in context.',
+          'ID of the workflow to run. Always pass this explicitly — outside a workflow-scoped chat there is no current workflow to fall back to, and the run is rejected without it.',
       },
       workflow_input: {
         type: 'object',
         description:
           "JSON object matching the target trigger's inputSchema (from get_workflow_run_options). For external/webhook triggers this is the event payload; for API/Input triggers it is the form fields.",
       },
     },
-    required: ['stopAfterBlockId'],
+    required: ['workflowId', 'stopAfterBlockId'],
   },
   clientExecutable: true,
   requiresApproval: true,

apps/sim/lib/copilot/generated/tool-schemas-v1.ts

@@ -4145,14 +4145,14 @@ export const TOOL_RUNTIME_SCHEMAS: Record<string, ToolRuntimeSchemaEntry> = {
         workflowId: {
           type: 'string',
           description:
-            'Optional workflow ID to run. If not provided, uses the current workflow in context.',
+            'ID of the workflow to run. Always pass this explicitly — outside a workflow-scoped chat there is no current workflow to fall back to, and the run is rejected without it.',
         },
         workflow_input: {
           type: 'object',
           description: 'JSON object with key-value mappings where each key is an input field name',
         },
       },
-      required: ['blockId'],
+      required: ['workflowId', 'blockId'],
     },
     resultSchema: undefined,
   },
@@ -4270,14 +4270,14 @@ export const TOOL_RUNTIME_SCHEMAS: Record<string, ToolRuntimeSchemaEntry> = {
         workflowId: {
           type: 'string',
           description:
-            'Optional workflow ID to run. If not provided, uses the current workflow in context.',
+            'ID of the workflow to run. Always pass this explicitly — outside a workflow-scoped chat there is no current workflow to fall back to, and the run is rejected without it.',
         },
         workflow_input: {
           type: 'object',
           description: 'JSON object with key-value mappings where each key is an input field name',
         },
       },
-      required: ['startBlockId'],
+      required: ['workflowId', 'startBlockId'],
     },
     resultSchema: undefined,
   },
@@ -4313,14 +4313,15 @@ export const TOOL_RUNTIME_SCHEMAS: Record<string, ToolRuntimeSchemaEntry> = {
         workflowId: {
           type: 'string',
           description:
-            'Optional workflow ID to run. If not provided, uses the current workflow in context.',
+            'ID of the workflow to run. Always pass this explicitly — outside a workflow-scoped chat there is no current workflow to fall back to, and the run is rejected without it.',
         },
         workflow_input: {
           type: 'object',
           description:
             "JSON object matching the target trigger's inputSchema (from get_workflow_run_options). For external/webhook triggers this is the event payload; for API/Input triggers it is the form fields.",
         },
       },
+      required: ['workflowId'],
     },
     resultSchema: undefined,
   },
@@ -4355,15 +4356,15 @@ export const TOOL_RUNTIME_SCHEMAS: Record<string, ToolRuntimeSchemaEntry> = {
         workflowId: {
           type: 'string',
           description:
-            'Optional workflow ID to run. If not provided, uses the current workflow in context.',
+            'ID of the workflow to run. Always pass this explicitly — outside a workflow-scoped chat there is no current workflow to fall back to, and the run is rejected without it.',
         },
         workflow_input: {
           type: 'object',
           description:
             "JSON object matching the target trigger's inputSchema (from get_workflow_run_options). For external/webhook triggers this is the event payload; for API/Input triggers it is the form fields.",
         },
       },
-      required: ['stopAfterBlockId'],
+      required: ['workflowId', 'stopAfterBlockId'],
     },
     resultSchema: undefined,
   },

apps/sim/lib/copilot/generated/trace-attribute-values-v1.ts

@@ -117,6 +117,16 @@ export const CopilotConfirmOutcome = {
 export type CopilotConfirmOutcomeKey = keyof typeof CopilotConfirmOutcome
 export type CopilotConfirmOutcomeValue = (typeof CopilotConfirmOutcome)[CopilotConfirmOutcomeKey]
 
+export const CopilotDegradedReason = {
+  BindingRejected: 'binding_rejected',
+  ClientPickupTimeout: 'client_pickup_timeout',
+  MissingToolResult: 'missing_tool_result',
+  StreamDeadBeforeDispatch: 'stream_dead_before_dispatch',
+} as const
+
+export type CopilotDegradedReasonKey = keyof typeof CopilotDegradedReason
+export type CopilotDegradedReasonValue = (typeof CopilotDegradedReason)[CopilotDegradedReasonKey]
+
 export const CopilotFinalizeOutcome = {
   Aborted: 'aborted',
   Error: 'error',

apps/sim/lib/copilot/generated/trace-attributes-v1.ts

@@ -189,6 +189,7 @@ export const TraceAttr = {
   CopilotCommandsCount: 'copilot.commands.count',
   CopilotConfirmOutcome: 'copilot.confirm.outcome',
   CopilotContextsCount: 'copilot.contexts.count',
+  CopilotDegradedReason: 'copilot.degraded.reason',
   CopilotExecutionId: 'copilot.execution.id',
   CopilotFileAttachmentsCount: 'copilot.file_attachments.count',
   CopilotFinalizeOutcome: 'copilot.finalize.outcome',
@@ -833,6 +834,7 @@ export const TraceAttrValues: readonly TraceAttrValue[] = [
   'copilot.commands.count',
   'copilot.confirm.outcome',
   'copilot.contexts.count',
+  'copilot.degraded.reason',
   'copilot.execution.id',
   'copilot.file_attachments.count',
   'copilot.finalize.outcome',