Support importing engine.mcp.tool-timeout from shared workflows

[lpcox]

Problem

Shared workflows that wrap slow HTTP MCP servers (e.g., Repo Mind Light) cannot propagate the engine.mcp.tool-timeout setting to their consumers. This forces every consumer to manually add:

engine:
  mcp:
    tool-timeout: "10m"

...even though the shared workflow author knows the correct timeout for their MCP server.

Today, tools.timeout and tools.startup-timeout are merged during shared workflow import, but engine.mcp.tool-timeout lives under the engine: section which is not imported.

Context

• Issue: MCP gateway tool timeout should be configurable by reusable workflow components gh-aw-mcpg#5190
• Comment with analysis: MCP gateway tool timeout should be configurable by reusable workflow components gh-aw-mcpg#5190 (comment)

Proposed Solution

Make engine.mcp.tool-timeout importable from shared workflows during the import merge phase.

When a consumer imports a shared workflow that declares engine.mcp.tool-timeout, the compiler should merge that value into the consumer's effective configuration — following the same precedence rules as other imported settings (consumer explicitly set > imported value > default).

Example

Shared workflow (shared/repo-mind-light.md):

---
description: "Repo Mind Light shared component"
mcp-servers:
  repo-mind:
    url: http://127.0.0.1:8000/mcp
    allowed:
      - query

engine:
  mcp:
    tool-timeout: "10m"

tools:
  timeout: 600
  startup-timeout: 600
---

Consumer workflow:

---
imports:
  - shared/repo-mind-light.md
engine: copilot
---

Expected behavior: The compiled workflow uses tool-timeout: "10m" from the shared workflow without the consumer needing to specify it.

Override behavior: If the consumer explicitly sets engine.mcp.tool-timeout, their value takes precedence:

---
imports:
  - shared/repo-mind-light.md
engine:
  mcp:
    tool-timeout: "5m"  # Consumer override wins
---

Implementation Notes

• The import merge logic lives in pkg/workflow/compiler_orchestrator_tools.go and related import resolution code
• engine.mcp.tool-timeout extraction is in pkg/workflow/engine.go
• Validation is in pkg/workflow/engine_validation.go (10s–600s bounds)
• Gateway config propagation is in pkg/workflow/mcp_gateway_config.go
• Need to extend the import merge to include engine.mcp settings (at minimum tool-timeout and session-timeout)

Acceptance Criteria

• Shared workflows can declare engine.mcp.tool-timeout and have it propagated to consumers
• Consumer-specified engine.mcp.tool-timeout takes precedence over imported value
• Validation (10s–600s) applies to imported values
• Existing tools.timeout and tools.startup-timeout import behavior is unchanged
• Tests cover: import without override, import with consumer override, validation of imported value

Related

• MCP gateway tool timeout should be configurable by reusable workflow components gh-aw-mcpg#5190 — Original issue describing the problem from a consumer perspective
• Support configurable MCP gateway tool timeout via engine.mcp.tool-timeout #29630 — Initial engine.mcp.tool-timeout support

[szabta89]

Thanks for opening this. After applying engine.mcp.tool-timeout in the pull-requests issue triage workflow and looking at the generated lockfile, I think the desired fix should probably be a little broader than importing engine.mcp.tool-timeout as a second value.

The current situation is that a workflow wrapping a long-running MCP tool needs to reason about two separate timeout settings for what is effectively one user-visible operation:

tools:
  timeout: 600

engine:
  mcp:
    tool-timeout: "10m"

Those compile into different pieces of runtime plumbing:

• tools.timeout becomes GH_AW_TOOL_TIMEOUT=600 and controls the agent/tool-wrapper side of the tool call.
• engine.mcp.tool-timeout becomes toolTimeout in the MCP gateway JSON config and controls the gh-aw-mcpg -> HTTP MCP backend request timeout.

I understand why those are technically different layers, but from a workflow author and shared workflow consumer perspective they are not meaningfully different knobs. For a Repo Mind Light query, the user is just asking for one tool invocation to complete. If either side times out first, the operation fails. That means the practical timeout is constrained by whichever value is lower, and setting different values is surprising rather than useful.

This is especially awkward for shared workflows. The Repo Mind Light shared workflow can already set:

tools:
  timeout: 600
  startup-timeout: 600

and tools.timeout is import-merged into consumers. But that value is not enough for HTTP MCP tools, because the gateway backend can still time out separately unless each consumer also sets engine.mcp.tool-timeout. So consumers end up needing a second timeout that should conceptually match the first one.

My preference would be to unify these semantics instead of requiring shared workflows and consumers to carry both values forever. For example:

1. Treat tools.timeout as the single source of truth for tool invocation timeout, including MCP gateway backend requests.
2. When MCP servers are configured, have the compiler/gateway config derive toolTimeout from the effective merged tools.timeout value.
3. Keep engine.mcp.tool-timeout only as a backwards-compatible explicit override, or deprecate it once a migration path exists.
4. Preserve tools.startup-timeout as a separate concept, since startup/discovery is genuinely different from a running tool invocation.

That would make shared workflows work naturally: a shared Repo Mind Light component sets tools.timeout: 600 once, consumers inherit it through the existing import behavior, and gh-aw-mcpg receives the matching backend timeout without consumers needing to know about gateway-specific config.

If keeping separate MCP timeout syntax is still necessary, then importability of engine.mcp.tool-timeout is definitely better than the old sandbox.mcp.env.MCP_GATEWAY_TOOL_TIMEOUT workaround. But ergonomically I think the best outcome is a single timeout value for one tool invocation, with shared workflows able to set that value and consumers able to override it in the normal import precedence model.

Suggested acceptance criteria for the unified behavior:

• A shared workflow can set one tool invocation timeout that applies to both the agent wrapper and MCP gateway backend request.
• A consumer can override that timeout once, without needing to set both tools.timeout and engine.mcp.tool-timeout.
• The generated lockfile uses a consistent effective timeout for GH_AW_TOOL_TIMEOUT and MCP gateway toolTimeout unless an explicit legacy override is present.
• Existing workflows using engine.mcp.tool-timeout continue to compile, with clear precedence rules if both values are present.
• tools.startup-timeout remains separate and continues to control startup/discovery behavior only.

[szabta89]

Note that Repo Mind Light does not actually need 10 minutes. The run time is determined by one LLM invocation through CAPI. This typically takes 30-90 seconds, it can take more when CAPI is overloaded and rate limiting kicks in.