[aryasaatvik]

Summary

Make approval-required MCP executions return a pause envelope promptly while preserving Cloudflare Durable Object hibernation. Normal tool calls can hibernate after the active POST response drains. Paused approvals hold a bounded pending-approval lease, then release it on approve, decline, or timeout.

This keeps the Cloudflare Agents event-store path intact. It does not use the earlier getEventStore() => undefined workaround.

Changes

• Add pausedExecutionCount() / hasPausedExecutions() on ExecutionEngine.
• Add shared Cloudflare MCP session alarm policy for idle sessions with paused continuations.
• Add PausedExecutionHooks to the MCP host so hosts can observe pause and resume boundaries.
• In McpAgentSessionDOBase, add active POST response wait around Cloudflare Agents streamable HTTP dispatch, bounded pending-approval leases, auto-decline on approval timeout, and lease cleanup on resume and runtime close.
• Wire pausedExecutionHooks through host-cloudflare MCP sessions.
• Align browser approval wait with the bounded approval lease.
• Keep pause lifecycle telemetry aligned with existing conventions: MCP host code uses debug logging and span annotations, while Cloudflare DO logs stay focused on exceptional boundary events.
• Compact execution-history interaction payloads so pause creation does not serialize arbitrary full tool context.
• Resolve OpenAPI-backed annotations with getOperation(...) point lookups instead of scanning every operation in large specs.
• Include the lockfile update from the working tree.

Live verification

Final deployed Worker version tested: 0aa27611-e865-4fbe-8576-48df95ee1230.

A subagent called tools.cloudflare_api.org.aryalabs.user.userUserDetails({}) through Executor MCP with approval required:

• pause returned: yes
• executionId: exec_5df462bc-3502-4ef7-9472-7488ec7f524f
• pause wall time: 2.0445s
• decline resume wall time: 1.0295s
• outcome: expected declined-tool error
• timeout or memory reset: none

Local validation

• packages/hosts/mcp: bun run test src/tool-server.test.ts, 38 passed
• packages/hosts/cloudflare: bun run test src/mcp/session-alarm-policy.test.ts, 5 passed
• packages/plugins/execution-history: bun run test src/sdk/store.test.ts src/sdk/store-list.test.ts, 6 passed
• packages/plugins/openapi: bun run test src/sdk/store.test.ts src/sdk/plugin.test.ts, 26 passed
• bun run typecheck for packages/hosts/mcp, packages/hosts/cloudflare, packages/core/sdk, packages/plugins/execution-history, and packages/plugins/openapi
• touched-file bunx oxfmt --check
• touched-file bunx oxlint --deny-warnings

Some package typechecks still print existing unrelated suggestions or warnings, but exited successfully.

[greptile-apps]

Greptile Summary

This PR adds bounded pending-approval leases to Cloudflare Durable Object MCP sessions so that paused, approval-required executions return a pause envelope promptly and the DO can safely hibernate between requests. A PausedExecutionHooks interface lets the host observe pause and resume boundaries, a new session-alarm-policy module encodes the alarm decision logic (with a hard cap at SESSION_TIMEOUT_MS + PAUSED_EXECUTION_LEASE_MS), and auto-decline fires after a 4-minute lease if no user response arrives.

• Pending-approval lease (startPendingApprovalLease): calls keepAlive() and sets a setTimeout(4 min) that records a decline and resolves the approval deferred; expirePendingApproval skips direct engine.resume when a waiter exists, letting the browser flow drive resumption.
• Alarm policy (decideSessionAlarm): deterministic pure function covering idle_within_timeout, extend_paused_lease (single extension, bounded by MAX_PAUSED_SESSION_IDLE_MS), and destroy_idle_session; fully unit-tested with the cap assertion.
• Payload compaction in execution-history (interactionPayloadOf): truncates per-string values to 300 chars and limits to 25 arg keys, preventing large tool contexts from bloating interaction records.

Confidence Score: 4/5

The core lease lifecycle and alarm policy are well-reasoned and thoroughly tested; the main subtlety is a non-operational early keepAlive release in the expiry-with-waiter path.

All three previously flagged issues from earlier review rounds (unbounded lease extension, missing alarm-policy test, and the atob crash) are addressed. The dual-dispose handling in releasePendingApprovalLease is idempotent and correct. The one remaining observation — that expirePendingApproval's Effect.ensuring disposes the keepAlive before the browser-flow engine.resume completes — is non-blocking because the active HTTP request independently keeps the DO alive during that window. No correctness regressions were found in the alarm policy refactor, the payload compaction, or the OpenAPI point-lookup change.

packages/hosts/cloudflare/src/mcp/agent-session-durable-object.ts — specifically the interplay between expirePendingApproval's Effect.ensuring and the browser-flow onResumeSettled in the waiter-present code path.

Important Files Changed

Filename	Overview
packages/hosts/cloudflare/src/mcp/agent-session-durable-object.ts	Major addition: pending-approval lease system (keepAlive, setTimeout expiry, auto-decline), onConnect override with active POST response drain, alarm() rewritten with decideSessionAlarm policy, and cleanupUnaddressableSessionAlarm guard. Core logic is sound with careful single-thread reasoning; the expiry/waiter coordination handles the waiter-present vs. waiter-absent paths correctly.
packages/hosts/cloudflare/src/mcp/session-alarm-policy.ts	New pure policy module with well-defined constants: SESSION_TIMEOUT_MS (5 min), PAUSED_EXECUTION_LEASE_MS (4 min), MAX_PAUSED_SESSION_IDLE_MS (9 min cap). decideSessionAlarm is deterministic and fully covered by the new test suite; the cap correctly limits the extension to one lease window.
packages/hosts/cloudflare/src/mcp/session-alarm-policy.test.ts	New test file covering all five branches of decideSessionAlarm including the idle_within_timeout case with paused work (addressing previous review feedback), the cap boundary, and normal destroy. Full coverage, no gaps.
packages/hosts/mcp/src/tool-server.ts	PausedExecutionHooks interface added, PAUSED_APPROVAL_TIMEOUT_MS exported, BROWSER_APPROVAL_WAIT_TIMEOUT_MS set 1 s beyond the lease timer to ensure expiry fires first. resumeWithLifecycle wraps onResumeStarted/onResumeSettled correctly for model and browser resume paths.
packages/hosts/mcp/src/tool-server.test.ts	New test verifies complete pause/resume lifecycle event sequence covering the multi-pause continuation path.
packages/core/execution/src/engine.ts	Adds pausedExecutionCount() and hasPausedExecutions() as thin wrappers over the existing pausedExecutions Map; straightforward and correct.
packages/plugins/execution-history/src/sdk/store.ts	interactionPayloadOf compacts args to at most 25 keys / 300 chars per string, preventing large tool contexts from bloating the interaction record. requestedSchema is still stored in full for FormElicitation (intentional for UI rendering).
packages/plugins/openapi/src/sdk/backing.ts	resolveOpenApiBackedAnnotations switches from listOperations (bulk scan) to getOperation point lookups per tool, trading N sequential queries for avoiding full-spec materialization on large OpenAPI specs.
packages/hosts/cloudflare/src/mcp/session-durable-object.ts	Integrates decideSessionAlarm into runAlarm, adding extend_paused_lease branch alongside the existing destroy/heartbeat paths. SESSION_TIMEOUT_MS de-duplicated by importing from session-alarm-policy.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Model
    participant McpToolServer
    participant Engine
    participant McpAgentSessionDO
    participant BrowserUser

    Model->>McpToolServer: execute(code)
    McpToolServer->>Engine: executeWithPause(code)
    Engine-->>McpToolServer: paused(executionId)
    McpToolServer->>McpAgentSessionDO: onExecutionPaused(executionId)
    McpAgentSessionDO->>McpAgentSessionDO: keepAlive() + setTimeout(4min, expire)
    McpToolServer->>McpAgentSessionDO: waitForBrowserApprovalResponse(executionId)
    McpAgentSessionDO->>McpAgentSessionDO: create approvalWaiter Deferred
    McpToolServer-->>Model: pause envelope (browser approval URL)

    alt User approves within 4 min
        BrowserUser->>McpAgentSessionDO: resumeExecutionForApproval(accept)
        McpAgentSessionDO->>McpAgentSessionDO: recordApprovalResponse(accept)
        McpAgentSessionDO->>McpAgentSessionDO: Deferred.succeed(waiter, accept)
        McpAgentSessionDO-->>McpToolServer: accept response
        McpToolServer->>McpAgentSessionDO: onResumeStarted → clearTimeout
        McpToolServer->>Engine: resume(executionId, accept)
        Engine-->>McpToolServer: completed result
        McpToolServer->>McpAgentSessionDO: onResumeSettled → releasePendingApprovalLease
        McpToolServer-->>Model: tool result
    else Approval timeout (4 min)
        McpAgentSessionDO->>McpAgentSessionDO: expirePendingApproval(executionId)
        McpAgentSessionDO->>McpAgentSessionDO: recordApprovalResponse(decline) + Deferred.succeed(waiter, decline)
        McpAgentSessionDO-->>McpToolServer: decline response (via waiter)
        McpToolServer->>Engine: resume(executionId, decline)
        Engine-->>McpToolServer: completed/error result
        McpAgentSessionDO->>McpAgentSessionDO: releasePendingApprovalLease (via ensuring)
        McpToolServer-->>Model: declined tool error
    end

    Note over McpAgentSessionDO: Session alarm: idleMs >= SESSION_TIMEOUT_MS<br/>+ pausedExecutionCount → extend_paused_lease<br/>capped at MAX_PAUSED_SESSION_IDLE_MS

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Model
    participant McpToolServer
    participant Engine
    participant McpAgentSessionDO
    participant BrowserUser

    Model->>McpToolServer: execute(code)
    McpToolServer->>Engine: executeWithPause(code)
    Engine-->>McpToolServer: paused(executionId)
    McpToolServer->>McpAgentSessionDO: onExecutionPaused(executionId)
    McpAgentSessionDO->>McpAgentSessionDO: keepAlive() + setTimeout(4min, expire)
    McpToolServer->>McpAgentSessionDO: waitForBrowserApprovalResponse(executionId)
    McpAgentSessionDO->>McpAgentSessionDO: create approvalWaiter Deferred
    McpToolServer-->>Model: pause envelope (browser approval URL)

    alt User approves within 4 min
        BrowserUser->>McpAgentSessionDO: resumeExecutionForApproval(accept)
        McpAgentSessionDO->>McpAgentSessionDO: recordApprovalResponse(accept)
        McpAgentSessionDO->>McpAgentSessionDO: Deferred.succeed(waiter, accept)
        McpAgentSessionDO-->>McpToolServer: accept response
        McpToolServer->>McpAgentSessionDO: onResumeStarted → clearTimeout
        McpToolServer->>Engine: resume(executionId, accept)
        Engine-->>McpToolServer: completed result
        McpToolServer->>McpAgentSessionDO: onResumeSettled → releasePendingApprovalLease
        McpToolServer-->>Model: tool result
    else Approval timeout (4 min)
        McpAgentSessionDO->>McpAgentSessionDO: expirePendingApproval(executionId)
        McpAgentSessionDO->>McpAgentSessionDO: recordApprovalResponse(decline) + Deferred.succeed(waiter, decline)
        McpAgentSessionDO-->>McpToolServer: decline response (via waiter)
        McpToolServer->>Engine: resume(executionId, decline)
        Engine-->>McpToolServer: completed/error result
        McpAgentSessionDO->>McpAgentSessionDO: releasePendingApprovalLease (via ensuring)
        McpToolServer-->>Model: declined tool error
    end

    Note over McpAgentSessionDO: Session alarm: idleMs >= SESSION_TIMEOUT_MS<br/>+ pausedExecutionCount → extend_paused_lease<br/>capped at MAX_PAUSED_SESSION_IDLE_MS

Loading

_{Reviews (5): Last reviewed commit: "fix(mcp): guard approval timeout races" | Re-trigger Greptile}