Check-level timeout does not propagate to nested workflow AI steps

[buger]

Bug Description

Setting timeout on a workflow-type check does not propagate to the AI steps inside the nested workflow. When the AI provider (e.g., Gemini) hangs indefinitely on an API call, the check-level timeout does not abort the hung request.

Steps to Reproduce

checks:
  chat:
    type: workflow
    workflow: assistant
    timeout: 120000  # 2 minutes
    args:
      question: "{{ conversation.current.text }}"

When the AI provider hangs (e.g., Gemini API stops responding mid-stream), the timeout: 120000 on the chat check does NOT abort the nested generate-response AI step. The process hangs indefinitely until killed externally.

Expected Behavior

The timeout on the parent workflow check should propagate to nested AI steps, or there should be a way to configure timeouts for nested workflow AI steps from the parent config.

Actual Behavior

• The generate-response AI step inside the assistant workflow has its own default timeout (30 minutes via config.ai?.timeout || 1800000)
• The parent check's timeout: 120000 is ignored for the nested workflow
• The only workarounds are env vars REQUEST_TIMEOUT and MAX_OPERATION_TIMEOUT which are global, not per-check

Workaround

Set REQUEST_TIMEOUT and MAX_OPERATION_TIMEOUT environment variables globally to control AI API call timeouts:

REQUEST_TIMEOUT=90000 MAX_OPERATION_TIMEOUT=180000 npx visor ...

Environment

• Visor v0.1.175
• Model: gemini-3-flash-preview (intermittently hangs on API calls)
• Node.js v22.14.0

[probelabs]

Issue Analysis: Check-Level Timeout Not Propagating to Nested Workflow AI Steps

Summary

Thank you for reporting this issue, @buger! You've identified a clear gap in how timeouts are handled when a workflow-type check invokes a nested workflow. The parent check's timeout setting is not being propagated to AI steps within the nested workflow, causing indefinite hangs when the AI provider (e.g., Gemini) stops responding.

What I Understand

From your report and the code analysis, I can confirm:

1. The Problem: When you set timeout: 120000 on a workflow-type check, this timeout applies to the workflow execution wrapper but does not propagate to individual AI steps inside the nested workflow (like generate-response in the assistant workflow).

2. Current Behavior: Nested AI steps use their own default timeout (30 minutes via config.ai?.timeout || 1800000), completely ignoring the parent's shorter timeout.

3. Workaround Limitation: The REQUEST_TIMEOUT and MAX_OPERATION_TIMEOUT environment variables are global, not per-check, which is overly broad when you only want to timeout a specific check.

4. Expected Behavior: The parent check's timeout should constrain the total execution time of the nested workflow, including all AI steps within it.

Technical Analysis

After examining the codebase, here's what's happening:

Current Implementation

1. Workflow Provider (src/providers/workflow-check-provider.ts:663-891): The executeViaStateMachine method creates a child engine context for nested workflows but does not propagate timeout constraints to the child configuration.

2. Timeout Resolution (src/state-machine/dispatch/execution-invoker.ts:639-643): When executing individual checks, the timeout is resolved as:

   timeout: checkConfig.timeout || checkConfig.ai?.timeout || 1800000

   For nested workflow steps, checkConfig.timeout is undefined, so it falls back to the 30-minute default.

3. Overrides Mechanism (src/providers/workflow-check-provider.ts:600-626): The overrides feature exists but requires manually specifying timeout for each nested step, which defeats the purpose of a parent-level timeout.

Root Cause

The workflow provider creates an isolated child engine context (childContext) with a fresh configuration derived from projectWorkflowToGraph(). This child config has no knowledge of the parent check's timeout setting. The timeout is only enforced at the workflow wrapper level, not within the nested steps themselves.

Potential Solutions

Option 1: Propagate Timeout via Overrides (Quick Fix)

The workflow provider could automatically inject the parent's timeout into the child workflow's step configurations using the existing overrides mechanism:

// In executeViaStateMachine, after projectWorkflowToGraph
if (config.timeout) {
  for (const stepId of Object.keys(workflowConfig.checks || {})) {
    const step = workflowConfig.checks[stepId];
    if (!step.timeout && !step.ai?.timeout) {
      step.ai = step.ai || {};
      step.ai.timeout = config.timeout;
    }
  }
}

Pros: Leverages existing override mechanism; minimal code changes
Cons: Only applies to AI steps; doesn't enforce a hard deadline on the entire workflow

Option 2: Enforce Hard Deadline with AbortController (Robust)

Wrap the entire nested workflow execution in a timeout that aborts all in-flight operations:

const result = await Promise.race([
  runner.run(),
  new Promise((_, reject) => 
    setTimeout(() => reject(new Error('Workflow timeout')), config.timeout)
  )
]);

Pros: Enforces a hard deadline; aborts hung AI requests immediately
Cons: Requires AbortController integration across all providers

Option 3: Add inherit_timeout Configuration Option (Flexible)

Add a new workflow-level option to control timeout inheritance:

checks:
  chat:
    type: workflow
    workflow: assistant
    timeout: 120000
    inherit_timeout: true  # Propagate timeout to all nested steps

Pros: Backward compatible; gives users control
Cons: Adds configuration surface area

Questions for Clarification

1. Timeout Scope: Should the parent timeout apply to:

   • Each individual AI step within the workflow?
   • The total execution time of the entire workflow?
   • Both?

2. Override Behavior: If a nested step already has an explicit ai.timeout configured, should the parent timeout:

   • Override it?
   • Be ignored (step takes precedence)?
   • Apply a minimum (use the shorter of the two)?

3. Error Handling: When the timeout is hit, should the workflow:

   • Fail immediately with a timeout error?
   • Allow partial results from completed steps?

4. Use Case: Are you primarily concerned about:

   • Preventing indefinite hangs from unresponsive AI providers?
   • Enforcing SLAs on total workflow execution time?
   • Both?

Recommended Next Steps

1. Confirm the desired behavior based on the questions above
2. Choose an implementation approach (I'd recommend Option 2 for robustness)
3. Add tests for timeout propagation in nested workflows
4. Update documentation to clarify timeout behavior in the workflows guide

Workaround in the Meantime

Your current workaround using environment variables is the best available option:

REQUEST_TIMEOUT=90000 MAX_OPERATION_TIMEOUT=180000 npx visor ...

Alternatively, you can use the overrides feature to manually set timeouts on specific nested steps:

checks:
  chat:
    type: workflow
    workflow: assistant
    timeout: 120000
    overrides:
      generate-response:
        ai:
          timeout: 120000

Severity Assessment

• Category: Bug
• Priority: Medium (functional gap with viable workaround)
• Complexity: Moderate (requires careful coordination between workflow provider and execution engine)

References

• src/providers/workflow-check-provider.ts:663-891 – executeViaStateMachine method where child context is created
• src/state-machine/dispatch/execution-invoker.ts:639-643 – timeout resolution logic for individual checks
• src/providers/workflow-check-provider.ts:600-626 – applyOverrides method for step configuration overrides
• docs/timeouts.md – timeout configuration documentation
• docs/workflows.md:309-319 – workflow step configuration reference

---

Powered by Visor from Probelabs

💡 TIP: You can chat with Visor using /visor ask <your question>