fix(events-shim): recoverable wait_for_webhook claims with client ack (#2187)

Merged
AB
5d ago
+809-99

Summary

Fixes #2187.

In packages/events-shim/src/mcp.ts, wait_for_webhook previously claimed posts directly into the 'read' state via handOver(ctx) before the response reached the client. If the client disconnected or aborted the long-poll during that window (for instance, when a user types or cancels in Claude Code while a listen --stop-hook listener is waiting), the claimed posts were marked as read in the store but never delivered to the client, permanently losing messages.

While #2186 and #2194 improved listener hygiene, the in-flight response delivery window still existed. This PR implements recoverable claim-and-acknowledgement semantics with leased delivery and full backwards compatibility for legacy callers.


Key Changes

  1. Store-Level Leased Claims & Acknowledgements (types.ts, memory-store.ts):

    • Extended claimPending state parameter to support 'pending'. When claimed with state: 'pending', posts remain in the inbox under a lease timestamp (deliveredAt).
    • Leased posts are locked from concurrent readers, but if the client drops or aborts without acknowledging, the posts become claimable again once sendLeaseMs expires (deliveredAt < staleBefore).
    • Added ackPending(shimId, ids, at) to transition leased posts to 'read'.
    • Added releasePending(shimId, ids) to immediately clear deliveredAt, returning posts to the pool right away when a client intentionally aborts or exits without waiting for lease timeout.
  2. MCP Tools & Backwards Compatibility (mcp.ts):

    • Added ack_ids?: string[] and auto_ack?: boolean (defaults to true) to wait_for_webhook input schema. Existing / legacy callers that do not specify auto_ack retain the previous behavior (handOver with immediate read transition).
    • If ack_ids are supplied, they are acknowledged before the poll begins (supporting pipelined claim/ack loops).
    • Added dedicated ack_webhook_events ({ ids: string[] }) and release_webhook_events ({ ids: string[] }) tools.
  3. CLI Listeners (cli.ts):

    • Updated listenAsSessionOwner and cmdListen to poll with auto_ack: false.
    • Acknowledge posts only after successful handover to session delivery (deliver(...)) or stdout.
    • If a listener is stopped or aborted before successful delivery, unhanded posts trigger release_webhook_events to be reclaimed immediately by the next listener.
    • Updated WEBHOOKS_TOOL regex to recognize the new MCP tools.
  4. Testing (events-shim.test.ts):

    • Added 4 test cases:
      • wait_for_webhook with auto_ack: false keeps posts pending under lease until acknowledged
      • wait_for_webhook re-offers unacknowledged posts once the claim lease expires
      • wait_for_webhook with ack_ids acknowledges previous batch and claims the next pending posts
      • release_webhook_events immediately clears lease and makes posts claimable without waiting for lease expiry
    • All 44 tests in packages/events-shim/src/events-shim.test.ts pass cleanly.

Verification

  • npm --prefix packages/events-shim run build: TypeScript compiles with 0 errors.
  • npx vitest run packages/events-shim/src/events-shim.test.ts: 44/44 passed.

Autofix with [code]smith
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.

Host follow-ups (maintainer note)

ackPending/releasePending are optional on EventsShimStore. Hosts without them keep the old behaviour: wait_for_webhook marks posts read and the ack/release tools aren't offered. To adopt leases, these hosts need follow-ups:

  • Hosted Cloud (AgentWorkforce/cloud, packages/web/lib/events-shim/store.ts)
  • Self-hosted relay-control (src/events-shim/store.ts)

Each needs to implement both methods, store claim_token on claimPending(…, 'pending', at, token), and have the claimable/countPending SQL treat a pending row whose delivered_at is newer than staleBefore as leased.