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.mdindex 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### Fixeddiff --git a/docs/install.md b/docs/install.mdindex 2d9554b5..1732e2f4 100644--- a/docs/install.md+++ b/docs/install.md@@ -602,10 +602,11 @@ PowerShell bundle still drops an undelivered event.) Session startdoes a short bounded cleanup drain before fetching a handoff; cancellation-proneboundary 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 atomicallycommits its end watermark with its automatic handoff; a retry that finds thattransaction complete finishes any interrupted wiki commit, durable providerenqueue, and ingest-key completion without adding a second handoff. Thosediff --git a/hooks/_lib.sh b/hooks/_lib.shindex 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=000else_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=000fi@@ -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 0chmod 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.shindex 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 2assert_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/"*.jsonprintf '%s' '{"e":"unreachable"}' \