fix: round-2 review — two fix regressions, publish blockers, form bodies

Three of these were introduced by the previous round's fixes, which is
the point of reviewing a diff rather than a codebase.

A. The concurrency slot leaked when the runner threw. Wrapping dispatch
   in a try/catch made runner throws survivable, which exposed an
   asymmetry that had been unreachable: `activeRuns` was incremented
   before `runner.start()` and decremented at five separate later points,
   none of them a throw. After maxConcurrentRuns such throws the route
   stopped accepting anything, permanently, with nothing recorded. The
   slot now has one owner and is released in `finally` unless a
   background waiter takes it.

B. Destroying the request stream on a body-read failure killed the socket
   the response shares, so a planned 413 became a connection reset —
   which Hookdeck retries, re-buffering the oversized body each time,
   while our own counter logged a cancellation that never reached the
   wire. Only the timeout case destroys now, which is the only one still
   reading.

C. The config-error fallback route trusted the raw basePath. Since the
   invalid config may BE the basePath, `"/"` — rejected by the parser
   precisely because a prefix route there captures every Gateway request
   — would have been registered as a catch-all answering 503. Sanitised.

D. A permanently un-retryable orphan came back on every boot: the row was
   never settled when retryEvent failed, so it was re-found forever, one
   duplicate dead-letter per boot, and consumed the recovery budget ahead
   of events that could actually be recovered. A 404 is retention and
   settles; anything else may be transient and is left for the next boot.

Publishing: added LICENSE (MIT, as package.json and README already
claimed), a CI workflow, homepage/bugs, and a `files` field so npm ships
the plugin rather than the test suite. Genericised references to sibling
plugins that may not be public, and removed an internal connection name
from the smoke script — mutations there now require naming the connection
explicitly.

Also: form-encoded bodies are supported, since Twilio- and Slack-style
providers could otherwise never pass an ingress whose premise is "any
provider Hookdeck verifies"; a transport fault after the 202 re-queues or
dead-letters instead of only warning; agent turns document plainly that
they are fire-and-forget on the TaskFlow transport, with maxAgentRetries
warned about alongside sync; the shutdown budget is wired and shutdown no
longer pauses routes that no longer exist; a deliberate pause survives a
tunnel reconnect, where a shutdown pause is still lifted; pending
auto-resume timers are cancelled on service stop; disk-mode doctor no
longer reports the live Gateway's work as interrupted; and bulk replay
refuses in http mode rather than reporting success having matched
nothing.

One found by writing the tests: `stop()` registered its exit listener
after sending SIGTERM, so a child that exits promptly was missed and
teardown waited out the whole grace period before SIGKILLing a process
that had already gone.

586 tests.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: garethx

.env.example

@@ -9,7 +9,9 @@
 # a project you care about is still the wrong place to point it.
 HOOKDECK_TEST_API_KEY=
 
-# Optional. Defaults to https://api.hookdeck.com/2025-07-01
+# Optional, and read from the ENVIRONMENT only — this file is parsed for
+# HOOKDECK_TEST_API_KEY and the AGENT_TEST_* keys, nothing else.
+# Defaults to https://api.hookdeck.com/2025-07-01
 # HOOKDECK_API_BASE=
 
 # HOOKDECK_TEST_API_KEY above is also picked up by `npm run test:agent`. With it
@@ -26,3 +28,8 @@ HOOKDECK_TEST_API_KEY=
 # AGENT_TEST_ANTHROPIC_API_KEY=
 # AGENT_TEST_OPENAI_API_KEY=
 # AGENT_TEST_MODEL=anthropic/claude-haiku-4-5   # must be an id this openclaw build knows
+#
+# To let the smoke test CHANGE real Hookdeck state — it acknowledges one issue —
+# set both of these. Without them the run is read-only by construction.
+# AGENT_TEST_ALLOW_MUTATIONS=1
+# AGENT_TEST_MUTATION_CONNECTION=my-test-connection

.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run typecheck
+      # Excludes test/live, which needs a Hookdeck project and an API key.
+      - run: npm test

.gitignore

@@ -7,3 +7,4 @@ dist/
 !.env.example
 coverage/
 .vitest/
+*.tgz

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hookdeck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -97,7 +97,11 @@ You do not need to configure destination auth either. CLI destinations default t
 | `maxConcurrent` | `4` | Local admission control. In CLI transport this is the **only** limit — CLI destinations carry no `rate_limit` field. |
 | `busyRetryAfterSeconds` | `10` | `Retry-After` sent when deferring at capacity. |
 | `deferAttemptLimit` | `5` | Deferrals of the same event before the short `Retry-After` is dropped and exponential backoff takes over. Capacity that has not recovered after this many attempts is not the transient condition a short interval assumes. |
-| `dedupe.ttlHours` | `168` | Ledger retention. Must exceed Hookdeck's one-week retry ceiling. |
+| `pause.onShutdown` | `true` | Pause the connection before stopping the listener, so events are held rather than discarded. |
+| `pause.shutdownTimeoutMs` | `5000` | Budget for the whole teardown: pausing, draining and stopping children. |
+| `catchUp.enabled` | `true` | After a reconnect, replay requests that arrived while nothing was listening. |
+| `catchUp.minGapSeconds` | `30` | Below this, an outage is not worth a bulk replay. |
+| `dedupe.ttlHours` | `168` | Ledger retention, matching Hookdeck's one-week retry ceiling. Raise it if you extend retries beyond a week. |
 | `safety.allowRetryCancel` | `false` | See [Retry cancellation](#retry-cancellation). |
 | `routes.<id>.source` | — | **Required.** Hookdeck source name. |
 | `routes.<id>.path` | `/<id>` | Appended to `ingress.basePath`. Matched as a prefix — see below. |
@@ -261,7 +265,7 @@ Without `apiKey`, orphans are still detected, settled and dead-lettered — they
 
 ## Agent tools
 
-Eight tools, matching the shared contract's five operator verbs plus two read tools an agent host benefits from more than a CLI does.
+Eight tools: the shared contract's five operator verbs — `setup`, `status`, `pause`/`resume`, `replay`, `doctor` — plus three an agent host benefits from more than a CLI does. Two of those correlate what Hookdeck saw with what we did (`hookdeck_recent_deliveries`, `hookdeck_inspect_event`); the third, `hookdeck_issues`, is the dead-letter queue's own lifecycle.
 
 | Tool | Answers |
 |---|---|
@@ -341,8 +345,9 @@ Signature headers and resolved secrets are redacted from logs.
 
 Not yet implemented:
 
-- **No completion tracking for agent turns.** See [Agent turns](#agent-turns). Agent turns run through TaskFlow `run_task`, which exposes flow state rather than a completion signal, so `ackMode: "sync"` behaves as `async_retry`, and `deliver` and `lane` are recorded but not passed to the turn. Each is warned about at startup rather than failing quietly.
+- **Agent turns are fire-and-forget.** They run through TaskFlow `run_task`, which exposes flow state rather than a completion signal, so the delivery is acknowledged as soon as the run *starts*. Concretely: `ackMode: "sync"` does not wait, `maxAgentRetries` never fires, and a crash mid-run is **not** re-queued by boot recovery — the ledger row is already `succeeded`. Run durability belongs to the flow record from that point, and Hookdeck's guarantee covers delivery rather than completion. `deliver` and `lane` are likewise recorded but not passed to the turn. Every one of these warns at startup rather than failing quietly. `taskflow` and `wake` dispatch are unaffected.
 - **A signature authenticates the body, not the headers.** Hookdeck's HMAC covers the raw body only, with a project-level secret and no signed timestamp. So the event id and attempt count arrive unauthenticated, and a captured `(body, signature)` pair stays valid. Deduplication is what provides replay protection, an implausible attempt count is discarded rather than recorded, and provider verification at the Source is the layer that keeps unsigned traffic out in the first place.
+- **Form-encoded and JSON bodies only.** `application/x-www-form-urlencoded` (Twilio, Slack) and `application/json` are parsed; anything else is rejected permanently.
 - **List endpoints read the first page only.** `hookdeck_issues` and `hookdeck_recent_deliveries` report a real total from the count endpoint, but return one page of results.
 
 ## Development
@@ -353,11 +358,11 @@ npm test
 npm run typecheck
 ```
 
-559 tests, no Gateway or Hookdeck account required. Signature vectors are computed independently with `openssl`, `test/http-integration.test.ts` exercises the pipeline over a real socket including multi-byte UTF-8 and multi-chunk bodies, the store suites inject write failures at an exact call to prove the degradation rule, and `test/store-io.test.ts` runs against a real filesystem because that is the only place durability actually lives.
+586 tests, no Gateway or Hookdeck account required. Signature vectors are computed independently with `openssl`, `test/http-integration.test.ts` exercises the pipeline over a real socket including multi-byte UTF-8 and multi-chunk bodies, the store suites inject write failures at an exact call to prove the degradation rule, and `test/store-io.test.ts` runs against a real filesystem because that is the only place durability actually lives.
 
 ## Shared reliability contract
 
-This plugin conforms to a contract shared with the Hookdeck plugins for Hermes Agent and n8n, so that "what happens when the run fails" has the same answer in all three: the same verification rule, the same attempt-count deduplication, the same admission-control semantics, and the same operator verbs.
+This plugin conforms to a contract shared across Hookdeck's agent-platform plugins, so that "what happens when the run fails" has the same answer in each: the same verification rule, the same attempt-count deduplication, the same admission-control semantics, and the same operator verbs.
 
 Where this plugin adds something the contract does not require — retry cancellation, last-attempt dead-lettering — it defaults to off, so out-of-the-box wire behaviour matches its siblings.
 

index.ts

@@ -30,6 +30,7 @@ import {
 } from "./src/ingress/handler.js";
 import { deferFor, retryable } from "./src/protocol/outcome.js";
 import { reconcileOrphans } from "./src/recovery.js";
+import { cancelAllAutoResumes } from "./src/tools/pause.js";
 import { registerHookdeckTools } from "./src/tools/index.js";
 import type { ToolDeps } from "./src/tools/deps.js";
 import { openDiskState } from "./src/tools/state.js";
@@ -59,6 +60,24 @@ import {
 
 const PLUGIN_ID = "hookdeck";
 
+const DEFAULT_BASE_PATH = "/hookdeck";
+
+/**
+ * Picks a safe ingress path for the config-error route.
+ *
+ * Never trusts the value far enough to register a route that would swallow
+ * traffic belonging to something else.
+ */
+function fallbackBasePath(pluginConfig: unknown): string {
+  const raw = (pluginConfig as { ingress?: { basePath?: unknown } })?.ingress
+    ?.basePath;
+  if (typeof raw !== "string") return DEFAULT_BASE_PATH;
+
+  const trimmed = raw.trim().replace(/\/+$/, "");
+  if (!trimmed.startsWith("/") || trimmed === "") return DEFAULT_BASE_PATH;
+  return trimmed;
+}
+
 interface Runtime {
   ledger: Ledger;
   deadLetter: DeadLetterLog;
@@ -96,18 +115,15 @@ export default definePluginEntry({
           `config error at ${problem.path}: ${problem.message}`,
         );
       }
-      // The configured basePath, not the default: a deployment that moved the
-      // ingress would otherwise answer 404 on its real path during a config
-      // error, and the events would be lost rather than held.
-      const basePath =
-        typeof (api.pluginConfig as { ingress?: { basePath?: unknown } })
-          ?.ingress?.basePath === "string"
-          ? ((api.pluginConfig as { ingress: { basePath: string } }).ingress
-              .basePath satisfies string)
-          : "/hookdeck";
+      // The configured basePath where it is usable, so a deployment that moved
+      // its ingress still holds events rather than 404ing them. Sanitised
+      // first: the config being invalid is the whole reason we are here, and
+      // the invalid part may BE the basePath — `"/"` is rejected by the parser
+      // precisely because a prefix route there captures every Gateway request.
+      const basePath = fallbackBasePath(api.pluginConfig);
 
       api.registerHttpRoute({
-        path: basePath.startsWith("/") ? basePath : `/${basePath}`,
+        path: basePath,
         auth: "plugin",
         match: "prefix",
         replaceExisting: true,
@@ -549,6 +565,11 @@ export default definePluginEntry({
         // services are stopped BEFORE those hooks run, and `gateway_stop` is
         // capped at 5s. Connection pause and CLI teardown arrive with the
         // managed transport.
+        // Before anything is torn down: a pending auto-resume holds the deps
+        // it was created with, and firing after a restart would write through
+        // the previous run's stores.
+        cancelAllAutoResumes();
+
         const active = runtime;
         runtime = undefined;
         hostConfig = undefined;

openclaw.plugin.json

@@ -515,7 +515,7 @@
           "allowRetryCancel": {
             "type": "boolean",
             "default": false,
-            "description": "Permit 'Retry-After: -1' to cancel Hookdeck's automatic retries on permanently-invalid input. Off by default: with it off, wire behaviour matches the sibling Hermes and n8n plugins exactly."
+            "description": "Permit 'Retry-After: -1' to cancel Hookdeck's automatic retries on permanently-invalid input. Off by default: with it off, wire behaviour matches Hookdeck's other agent-platform plugins exactly."
           }
         }
       },

package.json

@@ -44,9 +44,20 @@
   },
   "scripts": {
     "test": "vitest run --exclude \"test/live/**\"",
-    "test:watch": "vitest",
+    "test:watch": "vitest --exclude \"test/live/**\"",
     "typecheck": "tsc --noEmit",
     "test:live": "vitest run test/live",
     "test:agent": "bash scripts/agent-smoke.sh"
-  }
+  },
+  "homepage": "https://github.com/hookdeck/hookdeck-openclaw#readme",
+  "bugs": {
+    "url": "https://github.com/hookdeck/hookdeck-openclaw/issues"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "openclaw.plugin.json",
+    "README.md",
+    "LICENSE"
+  ]
 }

scripts/agent-smoke.sh

@@ -47,6 +47,10 @@ HOOKDECK_KEY="$(read_env HOOKDECK_TEST_API_KEY)"
 # Off unless explicitly asked for. With a live key this run can then change
 # real Hookdeck state, so it must be a deliberate act, never a default.
 ALLOW_MUTATIONS="${AGENT_TEST_ALLOW_MUTATIONS:-}"
+# Which connection's issue the mutation question targets. Scoped on purpose:
+# "acknowledge the oldest issue" would let the model pick anything in the
+# project.
+MUTATION_CONNECTION="${AGENT_TEST_MUTATION_CONNECTION:-}"
 
 if [ -z "$ANTHROPIC_KEY" ] && [ -z "$OPENAI_KEY" ]; then
   echo "No model key found. Add AGENT_TEST_ANTHROPIC_API_KEY or AGENT_TEST_OPENAI_API_KEY to .env.local"
@@ -152,10 +156,17 @@ if [ -n "$HOOKDECK_KEY" ]; then
   # These only mean something with a key: without one the tools say they need
   # an operator, which is the other half of what this script proves.
   ask "Using the hookdeck tools, tell me about any open Hookdeck Issues. What kind are they, and what would I have to do to clear one?"
+  if [ -n "$ALLOW_MUTATIONS" ] && [ -z "$MUTATION_CONNECTION" ]; then
+    echo
+    echo "AGENT_TEST_ALLOW_MUTATIONS is set but AGENT_TEST_MUTATION_CONNECTION is not."
+    echo "Set it to the connection whose issue may be acknowledged, so the run cannot"
+    echo "pick an arbitrary one from your project."
+    exit 2
+  fi
   if [ -n "$ALLOW_MUTATIONS" ]; then
     # Scoped to one connection on purpose. "Acknowledge the oldest issue" would
     # let the model pick anything in the project.
-    ask "Acknowledge the oldest open Hookdeck issue for the hermes-livetest connection, then confirm what changed and what did NOT change."
+    ask "Acknowledge the oldest open Hookdeck issue for the $MUTATION_CONNECTION connection, then confirm what changed and what did NOT change."
   else
     # The refusal is the point: the correct answer names tools.allowMutations.
     ask "Acknowledge the oldest open Hookdeck issue for me."
@@ -175,6 +186,13 @@ if [ -n "$HOOKDECK_KEY" ]; then
   echo "failing and how. And the last question asked for a MUTATION on purpose —"
   echo "the correct outcome is a refusal naming tools.allowMutations, not an"
   echo "acknowledged issue."
+  if [ -n "$ALLOW_MUTATIONS" ] && [ -z "$MUTATION_CONNECTION" ]; then
+    echo
+    echo "AGENT_TEST_ALLOW_MUTATIONS is set but AGENT_TEST_MUTATION_CONNECTION is not."
+    echo "Set it to the connection whose issue may be acknowledged, so the run cannot"
+    echo "pick an arbitrary one from your project."
+    exit 2
+  fi
   if [ -n "$ALLOW_MUTATIONS" ]; then
     echo
     echo "MUTATIONS WERE ENABLED for this run, so the acknowledge really wrote."