Skip to content

feat(plugin-gateway): add dispatch wrappers and destroy hooks - #285

Merged
kodiakhq[bot] merged 1 commit into
mainfrom
feat/plugin-gateway-dispatch-hooks
Nov 13, 2026
Merged

kodiakhq[bot] merged 1 commit into
mainfrom
feat/plugin-gateway-dispatch-hooks

Conversation

@RedStar071

@RedStar071 RedStar071 commented Nov 13, 2026 •

Copy link
Copy Markdown
Member

🔗 Linked issue

Refs #261

🧭 Context

Second half of #261, as a stack, bottom to top:

  1. this PR: plugin-gateway dispatch wrappers and destroy hooks
  2. plugin-sharder exit and destroy hooks
  3. plugin-opentelemetry dispatch spans and the flushTraces() wiring, which resolves request: a plugin that traces the bot with OpenTelemetry #261

plugin-opentelemetry cannot give a dispatch a span of its own today. The raw and dispatch events don't wrap the async work, so the cache and database calls of a dispatch have no parent. Nor can it flush the traces when the gateway shuts down.

📚 Description

GatewayClient#addDispatchWrapper(wrapper) runs a wrapper around the processing of each dispatch received from Discord. The wrapper gets { payload, shardId, partition } and a run function to call once. Wrappers nest in the order they were added, and the dispatch timeout and error reporting stay outside all of them, so a failing dispatch is still reported through error.

GatewayClient#addDestroyHook(hook) runs a hook at the end of every destroy(), after the shards are disconnected and the queued dispatches are processed. Hooks also run when disconnecting fails. A hook that throws is reported through error and the next hooks still run.

Both return a function that removes what was added. Nothing changes for a client that adds neither.

As Pullfrog's plan noted, the READY reconcile and replayDispatch don't go through runDispatch, so they aren't wrapped. The README says so.

Key changes

  • GatewayClient: addDispatchWrapper, addDestroyHook, and the WrappedDispatch, DispatchWrapper and GatewayClientDestroyHook types.
  • tests/hooks.test.ts: nesting order, an AsyncLocalStorage store seen by listeners, failure reporting, removal, and hook order and failures on destroy.
  • README section and a minor changeset.

Type of Change

  • New feature (non-breaking change which adds functionality)
  • Bug fix (non-breaking change which fixes an issue)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Documentation change
  • Workflow / CI change

Pre-flight Checklist

  • I have read the Contributing Guidelines (if applicable)
  • My code follows the code style of this project
  • I have added tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes
  • I have updated the documentation accordingly
  • I added a changeset with pnpm changeset (or pnpm changeset add --empty if no release is needed). See .changeset/README.md.

🤖 AI disclosure: Claude Code was used on this PR. Code written with claude-opus-5-5; PR description written with claude-opus-5-5. AI policy.

RetriggerView in GreptileConfidence Score: 4/5

Fix the failed-shutdown ordering before merging so destroy hooks wait for pending dispatches.

Reviews (1) · Last reviewed commit: "feat(plugin-gateway): add dispatch wrapp..." · Reviewed by Greptile

addDispatchWrapper runs code around the processing of each dispatch
received from Discord, so a tracing span or an AsyncLocalStorage store
covers the cache writes and the listeners. addDestroyHook runs at the
end of every destroy(), once the shards are disconnected and the
dispatches processed, to flush what is left before the process exits.

Refs #261
@coldtea-pr-lens

coldtea-pr-lens Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Architecture

Architecture diagram for wolfstar-project/plugins at 89af4ad

Open the canvas


Data flow

No data-flow sequence changed in this PR.


Review

✨ Nothing flagged · reviewed 89af4ad


Tip

Run npx @coldtea/pr-lens-cli analyze --base origin/main on a branch, then npx @coldtea/pr-lens-cli render .pr-lens/graph.json. Same lenses, your own model key, before the pull request exists

🪧 More tips
  • Run npx skills add coldteadotai/pr-lens, then tell your coding agent: "Diagram the change you just made with PR Lens and attach it to the pull request."
  • Click the link under each diagram to open it on a canvas you can zoom, pan and step through
  • The diagrams are links. Click one to open it on the canvas, then press W or click play to walk through the change
  • Open a diagram on the canvas, then press W or click play to walk through the change one step at a time
  • The CLI's render reads .github/pr-lens.yml and applies your renames, exclusions and lane pins at draw time
  • Set github.comment.collapsed: true in .github/pr-lens.yml to fold the comment behind one View architecture… row. Drawing still runs as before
  • Set github.draw: on-demand in .github/pr-lens.yml and PR Lens stops drawing pull requests on its own. Comment @pr-lens draw on a pull request when you want that one drawn
  • Add .github/workflows/pr-lens.yml with coldteadotai/pr-lens/packages/action@v0 and your model provider's key as its api-key to run PR Lens from your own CI. Any /chat/completions endpoint works
  • After a push, tick Redraw to draw the latest commit
  • Switch GitHub to dark mode and the diagrams follow. The moving dots are this pull request's data in motion
  • Set github.description: false in .github/pr-lens.yml to stop PR Lens adding buttons to your PR descriptions

Thanks for using PR Lens! It's free for OSS. If it helped, a star helps other teams find it.  Star PR Lens on GitHub

@wolfstarbot wolfstarbot added the packages:plugin-gateway Changes in plugin-gateway label Nov 13, 2026

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found.

Reviewed changes

Reviewed the full diff of the single commit, then ran tests/hooks.test.ts (8 passing), oxlint and oxfmt --check on the branch.

  • addDispatchWrapper — wrappers live in an immutable array snapshot read once per dispatch, nest first-outermost around handleDispatch, and sit inside the dispatch timeout and reportError, so failures still reach error. A synchronous throw from a wrapper is caught by the same try.
  • addDestroyHook — hooks run in a finally at the end of disconnect(), after gateway.destroy, the session flush and idle(), so they also run when disconnecting fails and the original rejection still propagates. A throwing hook goes to error (or the logger) and the next hooks still run. Concurrent destroy() calls join one disconnect(), so hooks run once per destroy.
  • #keepSessions — moving the assignment into the try keeps the reset in the inner finally, so behavior is unchanged.
  • Docs and release — README section, minor changeset and the AI disclosure line are in place.

Pullfrog  | View workflow run | Using claude-sonnet-5-5 | 𝕏

@kodiakhq
kodiakhq Bot merged commit 54dbd76 into main Nov 13, 2026
19 checks passed
@kodiakhq
kodiakhq Bot deleted the feat/plugin-gateway-dispatch-hooks branch November 13, 2026 16:23
Comment on lines 679 to +681
} finally {
this.#keepSessions = false;
// Even when disconnecting failed: the process is likely to exit next, and what is left should still go out.
await this.#runDestroyHooks();

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Shutdown hooks run too early

If gateway.destroy() rejects while a dispatch is still running, disconnect() skips idle() and immediately runs the destroy hooks. A hook that flushes traces can finish before that dispatch ends, leaving its final spans unexported when the process exits. Wait for queued dispatches before running the hooks on the failure path too, while preserving the original disconnect error.

Prompt To Fix With AI
This is a comment left during a code review.
Path: packages/plugin-gateway/src/GatewayClient.ts
Line: 679-681

Comment:
**Shutdown hooks run too early**

If `gateway.destroy()` rejects while a dispatch is still running, `disconnect()` skips `idle()` and immediately runs the destroy hooks. A hook that flushes traces can finish before that dispatch ends, leaving its final spans unexported when the process exits. Wait for queued dispatches before running the hooks on the failure path too, while preserving the original disconnect error.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Fix in Claude Code Fix in Cursor

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

packages:plugin-gateway Changes in plugin-gateway

Projects

None yet

Development

Successfully merging this pull request may close these issues.

request: a plugin that traces the bot with OpenTelemetry

2 participants