hermes-agent/website/docs/user-guide
Teknium 5854aad8b5
feat(gateway): durable delivery-obligation ledger for final responses (#67181)
A final response generated but not confirmed-delivered was the one
artifact the gateway could lose without a trace: crash or planned
restart between finalize and platform ACK dropped it silently, and the
resume path re-ran the whole turn at full cost (#58818 P1, #41696,
#63695's gateway half).

gateway/delivery_ledger.py records each outbound final response in
state.db (same conventions as the async-delegation ledger: WAL, owner
pid + process-start-time liveness, bounded retention):

  pending -> attempting -> delivered | failed
  startup sweep on dead-owner rows -> redeliver | abandoned

Contract (the lessons from the closed delivery-outbox attempt #61790):
- obligation recorded BEFORE the first send attempt; cleared only on
  SendResult.success (destination acceptance, #51184)
- ambiguity is labeled, never silently retried: rows that were mid-send
  when the process died redeliver with a visible '♻️ Recovered reply —
  may be a duplicate' prefix (honest at-least-once)
- stable ids from session_key + inbound message id + content, so
  distinct threads/topics can never collide
- poison rows bounded: 3 attempts / 24h freshness -> abandoned; claim
  atomically re-stamps ownership so racing sweeps can't double-claim
- redelivery clears resume_pending for the session so the resume path
  never re-runs a turn whose answer the ledger already holds
- best-effort everywhere: ledger failure can never block or delay a send
- slash-command/ephemeral/empty responses are not recorded; cron and
  proactive delivery stay on DeliveryRouter (separate subsystem)

Config: gateway.delivery_ledger (default on; no version bump needed).

Validation: 30 ledger+producer tests; 352 blast-radius gateway tests
green; cross-process E2E (record in process A, kill it mid-send, claim
+ marker + redeliver in a fresh process B against the same state.db).
2026-07-19 00:45:32 -07:00
..
features docs(desktop): document the desktop plugin SDK (@hermes/plugin-sdk) (#67301) 2026-07-19 04:02:17 +00:00
messaging feat(gateway): durable delivery-obligation ledger for final responses (#67181) 2026-07-19 00:45:32 -07:00
secrets
skills
_category_.json
checkpoints-and-rollback.md
cli.md
configuration.md feat(agent): add display.show_commentary toggle for Codex commentary channel 2026-07-16 23:27:12 -07:00
configuring-models.md fix: harden /model --once against persistence and config-sync leaks 2026-07-18 14:01:56 -07:00
desktop.md docs(desktop): document the desktop plugin SDK (@hermes/plugin-sdk) (#67301) 2026-07-19 04:02:17 +00:00
docker.md
git-worktrees.md
managed-scope.md
multi-profile-gateways.md
profile-distributions.md
profiles.md
security.md
sessions.md
tui.md
windows-native.md
windows-wsl-quickstart.md