fix(events-shim): recoverable wait_for_webhook claims with client ack (#2187)
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
-
Store-Level Leased Claims & Acknowledgements (
types.ts,memory-store.ts):- Extended
claimPendingstate parameter to support'pending'. When claimed withstate: '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
sendLeaseMsexpires (deliveredAt < staleBefore). - Added
ackPending(shimId, ids, at)to transition leased posts to'read'. - Added
releasePending(shimId, ids)to immediately cleardeliveredAt, returning posts to the pool right away when a client intentionally aborts or exits without waiting for lease timeout.
- Extended
-
MCP Tools & Backwards Compatibility (
mcp.ts):- Added
ack_ids?: string[]andauto_ack?: boolean(defaults totrue) towait_for_webhookinput schema. Existing / legacy callers that do not specifyauto_ackretain the previous behavior (handOverwith immediatereadtransition). - If
ack_idsare supplied, they are acknowledged before the poll begins (supporting pipelined claim/ack loops). - Added dedicated
ack_webhook_events({ ids: string[] }) andrelease_webhook_events({ ids: string[] }) tools.
- Added
-
CLI Listeners (
cli.ts):- Updated
listenAsSessionOwnerandcmdListento poll withauto_ack: false. - Acknowledge posts only after successful handover to session delivery (
deliver(...)) orstdout. - If a listener is stopped or aborted before successful delivery, unhanded posts trigger
release_webhook_eventsto be reclaimed immediately by the next listener. - Updated
WEBHOOKS_TOOLregex to recognize the new MCP tools.
- Updated
-
Testing (
events-shim.test.ts):- Added 4 test cases:
wait_for_webhook with auto_ack: false keeps posts pending under lease until acknowledgedwait_for_webhook re-offers unacknowledged posts once the claim lease expireswait_for_webhook with ack_ids acknowledges previous batch and claims the next pending postsrelease_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.tspass cleanly.
- Added 4 test cases:
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](https://pr-comments-assets.blacksmith.sh/codesmith/autofix-with-codesmith-dark-3x.png)
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.