@rulemetric/hooks 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulemetric/hooks",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "publishConfig": {
     "access": "public"
   },

package/scripts/_post.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# RuleMetric: shared event-POST helper with bounded retry on transient failures.
+#
+# Why this exists: the event-capture hooks (post-tool-use, assistant-response,
+# user-prompt) POST to /api/sessions/:id/events fire-and-forget. The always-on
+# API may fast-503 under transient DB-pool load (the admission gate from
+# docs/plans/2026-06-28-db-ingest-load-admission-control.md, Phase 1). Without a
+# retry, a sheddable 503 silently drops the event — the highest-value capture
+# stream. This helper retries transient failures (503 / 429 / network) a few
+# times, honoring a capped Retry-After, and treats 4xx as permanent (no retry),
+# preserving the prior "log on failure, never block the hook" contract.
+#
+# Designed to be called inside the existing backgrounded `( ... ) &` subshell, so
+# it never delays the hook and a non-zero return cannot abort the caller. It is
+# defensively written to be safe under `set -euo pipefail`.
+
+# Bounded so the total wait stays inside the hooks' fire-and-forget budget.
+_RM_POST_MAX_ATTEMPTS="${RULEMETRIC_POST_MAX_ATTEMPTS:-3}"
+_RM_POST_RETRY_CAP_S="${RULEMETRIC_POST_RETRY_CAP_S:-2}"
+
+# _rulemetric_post_event <url> <auth_header> <payload> <log_tag> <seq>
+# Returns 0 on 2xx; 1 otherwise (after logging the final failure).
+_rulemetric_post_event() {
+  local url="$1" auth="$2" payload="$3" tag="$4" seq="$5"
+  local attempt=1 http_code="000" body="" hdr_file retry_after sleep_s
+
+  hdr_file=$(mktemp "${TMPDIR:-/tmp}/rm-post.XXXXXX" 2>/dev/null || true)
+
+  while [ "$attempt" -le "$_RM_POST_MAX_ATTEMPTS" ]; do
+    if [ -n "$hdr_file" ]; then
+      body=$(curl -s --noproxy '*' --max-time 4 -D "$hdr_file" -w '\n%{http_code}' \
+        -X POST "$url" -H "$auth" -H "Content-Type: application/json" \
+        -d "$payload" 2>&1) || true
+    else
+      body=$(curl -s --noproxy '*' --max-time 4 -w '\n%{http_code}' \
+        -X POST "$url" -H "$auth" -H "Content-Type: application/json" \
+        -d "$payload" 2>&1) || true
+    fi
+    http_code=$(printf '%s' "$body" | tail -1)
+    body=$(printf '%s' "$body" | sed '$d')
+
+    if [ "$http_code" = "200" ] || [ "$http_code" = "201" ]; then
+      [ -n "$hdr_file" ] && rm -f "$hdr_file"
+      return 0
+    fi
+
+    # Transient (service busy / rate-limited / network) → retry unless this was
+    # the last allowed attempt. Everything else (4xx) is permanent.
+    if [ "$http_code" = "503" ] || [ "$http_code" = "429" ] || [ "$http_code" = "000" ]; then
+      if [ "$attempt" -lt "$_RM_POST_MAX_ATTEMPTS" ]; then
+        retry_after=""
+        if [ -n "$hdr_file" ]; then
+          retry_after=$(grep -i '^Retry-After:' "$hdr_file" 2>/dev/null | tail -1 | tr -dc '0-9' || true)
+        fi
+        if [ -n "$retry_after" ] && [ "$retry_after" -gt 0 ] 2>/dev/null; then
+          sleep_s="$retry_after"
+        else
+          sleep_s="$attempt"   # 1s, 2s, ... linear backoff
+        fi
+        if [ "$sleep_s" -gt "$_RM_POST_RETRY_CAP_S" ] 2>/dev/null; then
+          sleep_s="$_RM_POST_RETRY_CAP_S"
+        fi
+        sleep "$sleep_s" 2>/dev/null || true
+        attempt=$((attempt + 1))
+        continue
+      fi
+    fi
+
+    break
+  done
+
+  _rulemetric_log "$tag" "error" "http_${http_code}_seq_${seq}_attempt_${attempt}: ${body}"
+  [ -n "$hdr_file" ] && rm -f "$hdr_file"
+  return 1
+}

package/scripts/assistant-response.sh

@@ -16,9 +16,7 @@ trap 'echo "rulemetric assistant-response failed at line $LINENO: $BASH_COMMAND"
 # Load config (env vars, ~/.config/rulemetric/env, or .env.local)
 source "$SCRIPT_DIR/_config.sh" 2>/dev/null || true
 
-# Bound the read so a hook runner that leaves stdin open cannot wedge the agent.
-INPUT=""
-IFS= read -r -d '' -t 2 INPUT || true
+INPUT=$(cat)
 source "$SCRIPT_DIR/_normalize.sh"
 
 if [ -z "$HOOK_SESSION_ID" ] || [ -z "${RULEMETRIC_API_URL:-}" ]; then
@@ -76,15 +74,7 @@ TOKEN_USAGE=$(jq -n \
 # Increment per-session sequence (same locking pattern as post-tool-use)
 SEQ_FILE="$TEMP_DIR/$HOOK_SESSION_ID.seq"
 LOCK_DIR="$TEMP_DIR/$HOOK_SESSION_ID.seqlock"
-SEQ_LOCK_TRIES=0
-while ! mkdir "$LOCK_DIR" 2>/dev/null; do
-  sleep 0.01
-  SEQ_LOCK_TRIES=$((SEQ_LOCK_TRIES + 1))
-  if [ "$SEQ_LOCK_TRIES" -ge 500 ]; then
-    _rulemetric_log "assistant-response" "skip" "seq_lock_timeout"
-    exit 0
-  fi
-done
+while ! mkdir "$LOCK_DIR" 2>/dev/null; do sleep 0.01; done
 SEQ=1
 if [ -f "$SEQ_FILE" ]; then
   SEQ=$(( $(cat "$SEQ_FILE") + 1 ))
@@ -125,12 +115,9 @@ PAYLOAD=$(jq -n \
 _rulemetric_log "assistant-response" "success"
 
 # Fire-and-forget (same error-logging pattern as post-tool-use)
-(CURL_OUT=$(curl -s --noproxy '*' --max-time 4 -w "\n%{http_code}" -X POST "${RULEMETRIC_API_URL}/api/sessions/${RW_SESSION_ID}/events" \
-  -H "$AUTH_HEADER" \
-  -H "Content-Type: application/json" \
-  -d "$PAYLOAD" 2>&1)
-  HTTP_CODE=$(echo "$CURL_OUT" | tail -1)
-  if [ "$HTTP_CODE" != "200" ] && [ "$HTTP_CODE" != "201" ]; then
-    BODY=$(echo "$CURL_OUT" | sed '$d')
-    _rulemetric_log "assistant-response" "error" "http_${HTTP_CODE}_seq_${SEQ}: ${BODY}"
-  fi) &
+# Fire-and-forget event POST, with bounded retry on a transient 503/429 so the
+# admission gate (db-wedge plan Phase 1) sheds load without dropping the event.
+source "$SCRIPT_DIR/_post.sh"
+_rulemetric_post_event \
+  "${RULEMETRIC_API_URL}/api/sessions/${RW_SESSION_ID}/events" \
+  "$AUTH_HEADER" "$PAYLOAD" "assistant-response" "$SEQ" &

package/scripts/post-retry.test.sh

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+# RuleMetric: test for the shared event-POST retry helper (_post.sh).
+#
+# Run with: bash packages/hooks/scripts/post-retry.test.sh
+# Exits non-zero on any failed assertion.
+#
+# Proves the Phase-0 contract for the db-wedge admission gate
+# (docs/plans/2026-06-28-db-ingest-load-admission-control.md):
+#   1. a transient 503 + Retry-After is RETRIED and the event lands (not dropped)
+#   2. a permanent 4xx is NOT retried (one request, then give up)
+#   3. sustained 503 gives up after RULEMETRIC_POST_MAX_ATTEMPTS and logs an error
+#
+# Uses a tiny stdlib-only Python stub server; no network, no real API.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+if [ -t 1 ]; then C_OK="\033[32m"; C_FAIL="\033[31m"; C_RST="\033[0m"; else C_OK=""; C_FAIL=""; C_RST=""; fi
+FAILURES=0; PASSES=0
+ok()   { printf "${C_OK}OK${C_RST}   %s\n" "$1"; PASSES=$((PASSES + 1)); }
+fail() { printf "${C_FAIL}FAIL${C_RST} %s\n" "$1"; FAILURES=$((FAILURES + 1)); }
+assert_eq() { if [ "$2" = "$3" ]; then ok "$1"; else fail "$1 (expected [$2], got [$3])"; fi; }
+
+PYTHON="$(command -v python3 || command -v python || true)"
+if [ -z "$PYTHON" ]; then echo "SKIP: python3 not found"; exit 0; fi
+
+WORK_ROOT=$(mktemp -d "${TMPDIR:-/tmp}/post-retry-test.XXXXXX")
+cleanup() { [ -n "${SERVER_PID:-}" ] && kill "$SERVER_PID" 2>/dev/null; rm -rf "$WORK_ROOT" 2>/dev/null || true; }
+trap cleanup EXIT
+
+# --- Stub server: counts requests, programmed by $MODE in a control file --------
+cat > "$WORK_ROOT/stub.py" <<'PY'
+import http.server, json, os, sys, threading
+mode = sys.argv[1]            # fail-once | always-503 | always-400
+count_file = sys.argv[2]
+n = 0
+lock = threading.Lock()
+class H(http.server.BaseHTTPRequestHandler):
+    def log_message(self, *a): pass
+    def do_POST(self):
+        global n
+        with lock:
+            n += 1; cur = n
+            open(count_file, "w").write(str(n))
+        length = int(self.headers.get('Content-Length', 0) or 0)
+        self.rfile.read(length)
+        if mode == "always-400":
+            self.send_response(400); self.end_headers(); self.wfile.write(b'{"error":"bad"}'); return
+        if mode == "always-503":
+            self.send_response(503); self.send_header("Retry-After", "1"); self.end_headers()
+            self.wfile.write(b'{"error":"busy"}'); return
+        # fail-once: 503 on first request, 200 thereafter
+        if cur == 1:
+            self.send_response(503); self.send_header("Retry-After", "1"); self.end_headers()
+            self.wfile.write(b'{"error":"busy"}')
+        else:
+            self.send_response(200); self.end_headers(); self.wfile.write(b'{"recorded":true}')
+srv = http.server.HTTPServer(("127.0.0.1", 0), H)
+print(srv.server_address[1], flush=True)
+srv.serve_forever()
+PY
+
+start_server() {
+  # $1 = mode; sets SERVER_PORT, SERVER_PID, COUNT_FILE
+  COUNT_FILE="$WORK_ROOT/count.$1"
+  : > "$COUNT_FILE"
+  exec 3< <("$PYTHON" "$WORK_ROOT/stub.py" "$1" "$COUNT_FILE")
+  SERVER_PID=$!
+  read -r SERVER_PORT <&3
+}
+stop_server() { [ -n "${SERVER_PID:-}" ] && kill "$SERVER_PID" 2>/dev/null; SERVER_PID=""; }
+req_count() { cat "$COUNT_FILE" 2>/dev/null || echo 0; }
+
+# --- Load the helper under test ----------------------------------------------
+LOG_FILE="$WORK_ROOT/log"
+_rulemetric_log() { echo "$*" >> "$LOG_FILE"; }   # stub: record log calls
+export RULEMETRIC_POST_MAX_ATTEMPTS=3
+export RULEMETRIC_POST_RETRY_CAP_S=1
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/_post.sh"
+
+AUTH="Authorization: Bearer test"
+PAYLOAD='{"sequence":1,"eventType":"tool_call"}'
+
+# --- Test 1: transient 503 + Retry-After is retried, event lands --------------
+start_server fail-once
+: > "$LOG_FILE"
+_rulemetric_post_event "http://127.0.0.1:$SERVER_PORT/events" "$AUTH" "$PAYLOAD" "test" 1
+rc=$?
+assert_eq "fail-once: returns success (0) after retry" "0" "$rc"
+assert_eq "fail-once: server saw exactly 2 requests (fail + retry)" "2" "$(req_count)"
+assert_eq "fail-once: no error logged on eventual success" "0" "$(wc -l < "$LOG_FILE" | tr -d ' ')"
+stop_server
+
+# --- Test 2: permanent 4xx is NOT retried ------------------------------------
+start_server always-400
+: > "$LOG_FILE"
+_rulemetric_post_event "http://127.0.0.1:$SERVER_PORT/events" "$AUTH" "$PAYLOAD" "test" 2
+rc=$?
+assert_eq "always-400: returns failure (1)" "1" "$rc"
+assert_eq "always-400: server saw exactly 1 request (no retry on 4xx)" "1" "$(req_count)"
+stop_server
+
+# --- Test 3: sustained 503 gives up after MAX_ATTEMPTS and logs ---------------
+start_server always-503
+: > "$LOG_FILE"
+_rulemetric_post_event "http://127.0.0.1:$SERVER_PORT/events" "$AUTH" "$PAYLOAD" "test" 3
+rc=$?
+assert_eq "always-503: returns failure (1) after exhausting attempts" "1" "$rc"
+assert_eq "always-503: server saw exactly MAX_ATTEMPTS (3) requests" "3" "$(req_count)"
+grep -q "http_503" "$LOG_FILE" && ok "always-503: logged an http_503 error" || fail "always-503: expected http_503 in log"
+stop_server
+
+# --- Summary -----------------------------------------------------------------
+echo
+echo "Passed: $PASSES   Failed: $FAILURES"
+[ "$FAILURES" -eq 0 ]

package/scripts/post-tool-use.sh

@@ -9,10 +9,8 @@ trap 'echo "rulemetric post-tool-use failed at line $LINENO: $BASH_COMMAND" >&2;
 # Load config (env vars, ~/.config/rulemetric/env, or .env.local)
 source "$SCRIPT_DIR/_config.sh" 2>/dev/null || true
 
-# Read hook input from stdin and normalize across tools. Bound the read so a
-# hook runner that leaves stdin open cannot wedge the agent.
-INPUT=""
-IFS= read -r -d '' -t 2 INPUT || true
+# Read hook input from stdin and normalize across tools
+INPUT=$(cat)
 source "$SCRIPT_DIR/_normalize.sh"
 
 # Session paper-trail: snapshot the full working tree to a shadow git ref for
@@ -53,15 +51,7 @@ fi
 # Increment sequence counter (atomic mkdir lock, works on macOS + Linux)
 SEQ_FILE="$TEMP_DIR/$HOOK_SESSION_ID.seq"
 LOCK_DIR="$TEMP_DIR/$HOOK_SESSION_ID.seqlock"
-SEQ_LOCK_TRIES=0
-while ! mkdir "$LOCK_DIR" 2>/dev/null; do
-  sleep 0.01
-  SEQ_LOCK_TRIES=$((SEQ_LOCK_TRIES + 1))
-  if [ "$SEQ_LOCK_TRIES" -ge 500 ]; then
-    _rulemetric_log "post-tool-use" "skip" "seq_lock_timeout"
-    exit 0
-  fi
-done
+while ! mkdir "$LOCK_DIR" 2>/dev/null; do sleep 0.01; done
 SEQ=1
 if [ -f "$SEQ_FILE" ]; then
   SEQ=$(( $(cat "$SEQ_FILE") + 1 ))
@@ -80,13 +70,9 @@ PAYLOAD=$(jq -n \
 
 _rulemetric_log "post-tool-use" "success"
 
-# Fire-and-forget (capture HTTP errors for debugging)
-(CURL_OUT=$(curl -s --noproxy '*' --max-time 4 -w "\n%{http_code}" -X POST "${RULEMETRIC_API_URL}/api/sessions/${RW_SESSION_ID}/events" \
-  -H "$AUTH_HEADER" \
-  -H "Content-Type: application/json" \
-  -d "$PAYLOAD" 2>&1)
-  HTTP_CODE=$(echo "$CURL_OUT" | tail -1)
-  if [ "$HTTP_CODE" != "200" ] && [ "$HTTP_CODE" != "201" ]; then
-    BODY=$(echo "$CURL_OUT" | sed '$d')
-    _rulemetric_log "post-tool-use" "error" "http_${HTTP_CODE}_seq_${SEQ}: ${BODY}"
-  fi) &
+# Fire-and-forget event POST, with bounded retry on a transient 503/429 so the
+# admission gate (db-wedge plan Phase 1) sheds load without dropping the event.
+source "$SCRIPT_DIR/_post.sh"
+_rulemetric_post_event \
+  "${RULEMETRIC_API_URL}/api/sessions/${RW_SESSION_ID}/events" \
+  "$AUTH_HEADER" "$PAYLOAD" "post-tool-use" "$SEQ" &

package/scripts/user-prompt.sh

@@ -9,10 +9,8 @@ trap 'echo "rulemetric user-prompt failed at line $LINENO: $BASH_COMMAND" >&2; _
 # Load config (env vars, ~/.config/rulemetric/env, or .env.local)
 source "$SCRIPT_DIR/_config.sh" 2>/dev/null || true
 
-# Read hook input from stdin and normalize across tools. Bound the read so a
-# hook runner that leaves stdin open cannot wedge the agent.
-INPUT=""
-IFS= read -r -d '' -t 2 INPUT || true
+# Read hook input from stdin and normalize across tools
+INPUT=$(cat)
 source "$SCRIPT_DIR/_normalize.sh"
 
 if [ -z "$HOOK_SESSION_ID" ] || [ -z "${RULEMETRIC_API_URL:-}" ]; then
@@ -41,15 +39,7 @@ fi
 # Increment sequence counter (atomic mkdir lock, works on macOS + Linux)
 SEQ_FILE="$TEMP_DIR/$HOOK_SESSION_ID.seq"
 LOCK_DIR="$TEMP_DIR/$HOOK_SESSION_ID.seqlock"
-SEQ_LOCK_TRIES=0
-while ! mkdir "$LOCK_DIR" 2>/dev/null; do
-  sleep 0.01
-  SEQ_LOCK_TRIES=$((SEQ_LOCK_TRIES + 1))
-  if [ "$SEQ_LOCK_TRIES" -ge 500 ]; then
-    _rulemetric_log "user-prompt" "skip" "seq_lock_timeout"
-    exit 0
-  fi
-done
+while ! mkdir "$LOCK_DIR" 2>/dev/null; do sleep 0.01; done
 SEQ=1
 if [ -f "$SEQ_FILE" ]; then
   SEQ=$(( $(cat "$SEQ_FILE") + 1 ))
@@ -57,16 +47,13 @@ fi
 echo "$SEQ" > "$SEQ_FILE"
 rmdir "$LOCK_DIR"
 
-# Fire-and-forget: send user message event (capture HTTP errors for debugging)
-(CURL_OUT=$(curl -s --noproxy '*' --max-time 4 -w "\n%{http_code}" -X POST "${RULEMETRIC_API_URL}/api/sessions/${RW_SESSION_ID}/events" \
-  -H "$AUTH_HEADER" \
-  -H "Content-Type: application/json" \
-  -d "{\"sequence\":$SEQ,\"eventType\":\"user_message\",\"content\":$(printf '%s' "$HOOK_PROMPT" | jq -Rs .),\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%S.000Z)\"}" 2>&1)
-  HTTP_CODE=$(echo "$CURL_OUT" | tail -1)
-  if [ "$HTTP_CODE" != "200" ] && [ "$HTTP_CODE" != "201" ]; then
-    BODY=$(echo "$CURL_OUT" | sed '$d')
-    _rulemetric_log "user-prompt" "error" "http_${HTTP_CODE}_seq_${SEQ}: ${BODY}"
-  fi) &
+# Fire-and-forget event POST, with bounded retry on a transient 503/429 so the
+# admission gate (db-wedge plan Phase 1) sheds load without dropping the event.
+PAYLOAD="{\"sequence\":$SEQ,\"eventType\":\"user_message\",\"content\":$(printf '%s' "$HOOK_PROMPT" | jq -Rs .),\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%S.000Z)\"}"
+source "$SCRIPT_DIR/_post.sh"
+_rulemetric_post_event \
+  "${RULEMETRIC_API_URL}/api/sessions/${RW_SESSION_ID}/events" \
+  "$AUTH_HEADER" "$PAYLOAD" "user-prompt" "$SEQ" &
 
 _rulemetric_log "user-prompt" "success"