Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

fix(hooks): preserve ingest key across shell retry

Felipe Neves Ricardo032d8dfe659e
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f82367a3..9f29d119 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+### Fixed
+- The POSIX shell hook bundle now assigns an `ingest_key` before its initial
+ delivery and preserves that key when spooling the event, preventing a replay
+ from creating a duplicate observation when the server committed the first
+ request but its response was lost (#729).
+
## [2.2.1] - 2026-09-12
### Fixed
diff --git a/docs/install.md b/docs/install.md
index 2d9554b5..1732e2f4 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -602,10 +602,11 @@ PowerShell bundle still drops an undelivered event.) Session start
does a short bounded cleanup drain before fetching a handoff; cancellation-prone
boundary events (`stop`, `pre-compact`, and `session-end`) start a detached
`hook-drain` helper so delivery does not depend on one shutdown hook surviving.
-Each spooled entry keeps one idempotency key across retries. A server that
-processed an event but lost the batch response will not duplicate its
-observation or completed session-end effects; if processing stopped after the
-observation commit, the retry re-runs downstream work. SessionEnd atomically
+The POSIX bundle assigns one idempotency key before its initial POST and keeps
+that key if the event enters the spool. A server that processed an event but
+lost the response will not duplicate its observation or completed session-end
+effects; if processing stopped after the observation commit, the retry re-runs
+downstream work. SessionEnd atomically
commits its end watermark with its automatic handoff; a retry that finds that
transaction complete finishes any interrupted wiki commit, durable provider
enqueue, and ingest-key completion without adding a second handoff. Those
diff --git a/hooks/_lib.sh b/hooks/_lib.sh
index d4f2fa23..e41885f3 100644
--- a/hooks/_lib.sh
+++ b/hooks/_lib.sh
@@ -460,13 +460,30 @@ ai_memory_auth_header_file() {
[ -r "$_amhf" ] && printf '%s' "$_amhf"
}
+# Mint the key before the first POST so an ambiguous delivery and its spool
+# replay carry the same identity. The server can then discard a replay whose
+# original response was lost after the observation committed.
+ai_memory_ingest_key() {
+ _amrnd=$(od -An -N8 -tx1 /dev/urandom 2>/dev/null | tr -d ' \n')
+ [ -n "$_amrnd" ] || _amrnd=$(printf '%s%s' "$(date +%s 2>/dev/null || printf '0')" "$$")
+ printf 'sh%s' "$_amrnd"
+}
+
+ai_memory_url_with_ingest_key() {
+ case "$1" in
+ *\?ingest_key=* | *\&ingest_key=*) printf '%s' "$1" ;;
+ *\?*) printf '%s&ingest_key=%s' "$1" "$(ai_memory_ingest_key)" ;;
+ *) printf '%s?ingest_key=%s' "$1" "$(ai_memory_ingest_key)" ;;
+ esac
+}
+
ai_memory_post_hook() {
- _amurl="$1"
+ _amurl=$(ai_memory_url_with_ingest_key "$1")
_ambody=$(cat)
_amhdr=$(ai_memory_auth_header_file || printf '')
if [ -n "${AI_MEMORY_AUTH_TOKEN:-}" ]; then
_amcode=$(printf '%s' "$_ambody" | curl -s --max-time 0.2 -o /dev/null \
- -w '%{http_code}' -X POST "$1" \
+ -w '%{http_code}' -X POST "$_amurl" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $AI_MEMORY_AUTH_TOKEN" \
--data-binary @- 2>/dev/null) || _amcode=000
@@ -474,13 +491,13 @@ ai_memory_post_hook() {
# `-H @file`: curl reads the header from disk, so the bearer never
# appears in curl's argv the way an inline `-H` would (#552).
_amcode=$(printf '%s' "$_ambody" | curl -s --max-time 0.2 -o /dev/null \
- -w '%{http_code}' -X POST "$1" \
+ -w '%{http_code}' -X POST "$_amurl" \
-H "Content-Type: application/json" \
-H @"$_amhdr" \
--data-binary @- 2>/dev/null) || _amcode=000
else
_amcode=$(printf '%s' "$_ambody" | curl -s --max-time 0.2 -o /dev/null \
- -w '%{http_code}' -X POST "$1" \
+ -w '%{http_code}' -X POST "$_amurl" \
-H "Content-Type: application/json" \
--data-binary @- 2>/dev/null) || _amcode=000
fi
@@ -573,27 +590,14 @@ ai_memory_spool_token() {
| head -n 1 | tr -d '\r\n'
}
-# Idempotency key minted ONCE at spool time and baked into the URL, so this
-# bundle's drain and a concurrent `ai-memory hook-drain` cannot double-ingest.
-ai_memory_ingest_key() {
- _amrnd=$(od -An -N8 -tx1 /dev/urandom 2>/dev/null | tr -d ' \n')
- [ -n "$_amrnd" ] || _amrnd=$(printf '%s%s' "$(date +%s 2>/dev/null || printf '0')" "$$")
- printf 'sh%s' "$_amrnd"
-}
-
# Persist one undelivered event. Best-effort on top of best-effort capture:
# every failure path returns 0 so a hook never fails because of the spool.
ai_memory_spool_event() {
- _amsurl="$1"
+ _amsurl=$(ai_memory_url_with_ingest_key "$1")
_amsbody="$2"
_amsdir=$(ai_memory_spool_dir)
mkdir -p "$_amsdir" 2>/dev/null || return 0
chmod 700 "$_amsdir" 2>/dev/null || true
- case "$_amsurl" in
- *ingest_key=*) ;;
- *\?*) _amsurl="$_amsurl&ingest_key=$(ai_memory_ingest_key)" ;;
- *) _amsurl="$_amsurl?ingest_key=$(ai_memory_ingest_key)" ;;
- esac
_amstok=$(ai_memory_spool_token)
_amsnow=$(ai_memory_now_ms)
AI_MEMORY_SPOOL_SEQ=$((${AI_MEMORY_SPOOL_SEQ:-0} + 1))
diff --git a/tests/hooks/test_lib.sh b/tests/hooks/test_lib.sh
index a4c5cfcb..fa96f297 100755
--- a/tests/hooks/test_lib.sh
+++ b/tests/hooks/test_lib.sh
@@ -331,8 +331,11 @@ SPOOL_FILE=$(ls "$TMP/spool-data/hook-spool/"*.json 2>/dev/null | head -n 1)
assert_eq "spool_event writes one entry" "1" \
"$(ls "$TMP/spool-data/hook-spool/"*.json 2>/dev/null | wc -l | tr -d ' ')"
assert_eq "spooled body round-trips" "$SPOOL_BODY" "$(ai_memory_json_field body "$SPOOL_FILE")"
-assert_eq "spool_event mints an ingest_key" "yes" \
- "$(case "$(ai_memory_json_field url "$SPOOL_FILE")" in *ingest_key=sh*) printf yes ;; *) printf no ;; esac)"
+case "$(ai_memory_json_field url "$SPOOL_FILE")" in
+ *ingest_key=sh*) SPOOL_HAS_INGEST_KEY=yes ;;
+ *) SPOOL_HAS_INGEST_KEY=no ;;
+esac
+assert_eq "spool_event mints an ingest_key" "yes" "$SPOOL_HAS_INGEST_KEY"
assert_eq "spool entry is 0600" "600" \
"$(ls -l "$SPOOL_FILE" | cut -c2-10 | tr 'rwx-' '4210' | awk '{print substr($0,1,3)+0 substr($0,4,3)+0 substr($0,7,3)+0}' >/dev/null 2>&1; \
if [ -r "$SPOOL_FILE" ] && [ ! -x "$SPOOL_FILE" ]; then printf '600'; else printf 'other'; fi)"
@@ -349,6 +352,34 @@ ai_memory_json_field body "$TMP/spool-data/hook-spool/foreign.json" >/dev/null 2
assert_eq "json_field declines a \\u escape" "declined" "$FOREIGN"
rm -f "$TMP/spool-data/hook-spool/foreign.json"
+# A timeout can hide a successful server write. The initial attempt and the
+# spooled replay must carry the same key so the server can reject the replay.
+rm -f "$TMP/spool-data/hook-spool/"*.json
+CURL_ATTEMPT_FILE="$TMP/curl-attempt-url"
+curl() {
+ while [ "$#" -gt 0 ]; do
+ case "$1" in
+ http://* | https://*) printf '%s' "$1" >"$CURL_ATTEMPT_FILE" ;;
+ esac
+ shift
+ done
+ cat >/dev/null
+ return 28
+}
+printf '%s' '{"e":"ambiguous"}' \
+ | ai_memory_post_hook "http://127.0.0.1:49374/hook?event=stop&agent=cursor" >/dev/null 2>&1
+unset -f curl
+SPOOL_FILE=$(ls "$TMP/spool-data/hook-spool/"*.json 2>/dev/null | head -n 1)
+ATTEMPT_URL=$(cat "$CURL_ATTEMPT_FILE")
+SPOOL_URL=$(ai_memory_json_field url "$SPOOL_FILE")
+case "$ATTEMPT_URL" in
+ *ingest_key=sh*) ATTEMPT_HAS_INGEST_KEY=yes ;;
+ *) ATTEMPT_HAS_INGEST_KEY=no ;;
+esac
+assert_eq "post_hook keys the initial delivery" "yes" "$ATTEMPT_HAS_INGEST_KEY"
+assert_eq "post_hook preserves the key after an ambiguous delivery" \
+ "$ATTEMPT_URL" "$SPOOL_URL"
+
# An unreachable server must leave the event on disk instead of dropping it.
rm -f "$TMP/spool-data/hook-spool/"*.json
printf '%s' '{"e":"unreachable"}' \