coding_agent_timeout_contract - manishiitg/agentworks GitHub Wiki

Coding-Agent Timeout Contract

Coding-agent execution has several independent timeout layers. They must not be treated as one generic "agent timeout": each layer has a different owner and recovery action.

Effective runtime matrix

Layer Claude Code Codex CLI Cursor CLI Pi CLI Owner
Provider turn deadline none none none none Workflow/scheduler caller
Provider MCP-call control CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT = 90m mcp_servers.api-bridge.tool_timeout_sec = 90m no documented control no documented control CLI provider
mcpbridge HTTP timeout 5m ordinary, 90m long-running same same same mcpbridge
Server tool timeout 90m in desktop runtime same same same TOOL_EXECUTION_TIMEOUT
Persistent tmux idle retention 3h 3h 3h 3h Provider adapter
Initial prompt readiness 5m inactivity by default 10m inactivity, 90m absolute 5m 5m Provider adapter

The shared 90-minute MCP value is configured by CODING_AGENT_MCP_TOOL_TIMEOUT. Invalid, zero, or negative values fall back to 90 minutes so the final stuck-call guard cannot be accidentally disabled.

Required behavior

  1. Workflow and scheduler contexts own the business deadline. Provider adapters do not impose a shorter fixed turn deadline on an active tmux process.
  2. call_sub_agent and call_generic_agent are durable asynchronous starts. They return an execution_id immediately, so they do not hold an MCP request open for the child runtime.
  3. HTTP request cancellation is authoritative. Stopping a parent cancels an in-flight bridge/custom/virtual request; handlers must not replace the request context with context.Background().
  4. The 90-minute MCP value is only a final backstop for a silent or stuck call. It is not a normal completion signal and is not extended by tmux pane text.
  5. Timeout and cancellation errors identify the firing layer, tool, session, and configured timeout so operators can distinguish a bridge timeout from a workflow or prompt-readiness timeout.

Provider notes

  • Claude Code: the supported client watchdog is supplied in milliseconds.
  • Codex CLI: the bridge server's tool_timeout_sec is supplied in seconds.
  • Cursor CLI: current official CLI configuration documents MCP discovery and management but no MCP-call timeout setting. Do not invent an undocumented flag; rely on cancellation and mcpbridge.
  • Pi CLI: the current Pi settings and MCP adapter expose no MCP-call timeout setting. Do not invent an undocumented setting; rely on cancellation and mcpbridge.

Verification

Fast contract tests cover:

  • the shared default and override policy;
  • Claude millisecond and Codex second conversion;
  • cancellation propagation through custom and virtual per-tool HTTP routes;
  • deterministic timeout cleanup for a silent custom tool;
  • bridge timeout/cancellation diagnostics.

The real tmux path is exercised by mcp-agent test coding-agent-chat-e2e. It uses a temporary chat workspace, calls execute_shell_command through the actual api-bridge, waits through a silent sleep, sends live input during an active tool call, and stops the session during cleanup. Run it once per active provider when provider credentials are available.

Auto-synced from docs/ on main. Edit there, not here.

⚠️ **GitHub.com Fallback** ⚠️