Skip to content

feat(engine): add graceful exhaustion and deterministic replay cache - #255

Merged
Patel230 merged 2 commits into
mainfrom
feat/herm-followups
Aug 24, 2026
Merged

feat(engine): add graceful exhaustion and deterministic replay cache#255
Patel230 merged 2 commits into
mainfrom
feat/herm-followups

Conversation

@Patel230

Copy link
Copy Markdown
Contributor

Summary

Implements the remaining herm follow-ups (from PR #254's notes): graceful exhaustion and a deterministic replay cache. (The third noted item — staged skills mount — was dropped after analysis: hawk already injects only name+description into the prompt with digest-based incremental catalog updates and loads skill content on invocation, so the lazy-content pattern is already in place.)

1. Graceful turn-budget exhaustion synthesis (internal/engine/stream_exhaustion.go)

  • Port of herm's gracefulExhaustion: when the agent loop hits its limits (turn limit, token/time budget via checkGuardConditions), instead of emitting a bare "Limit reached" line it makes one final tools-disabled LLM call (Session.SynthesisForExhaustion) that synthesizes a coherent completion: what was accomplished, what remains, next steps.
  • Falls back to the static stop message whenever synthesis is unavailable (no LLM, empty conversation, cancelled context, failed call). Wired into all three limit paths in checkGuardConditions.

2. Deterministic replay cache (internal/replaycache)

  • Port of herm's request cache as a self-contained package: successful completions are persisted to disk under a SHA-256 key computed from a canonicalized request (messages incl. tool use/results, provider, model, max tokens) plus a config fingerprint; identical later requests replay the stored response.
  • Stream-event get/put primitives included for future streaming replay.
  • Opt-in wiring: setting HAWK_REPLAY_CACHE_DIR routes ChatService.Chat through the cache (chatWithReplay); unset (default) leaves the chat path byte-for-byte untouched. HAWK_REPLAY_FINGERPRINT invalidates whole suites at once. Writes are atomic 0600; errors are never cached.

Verification

  • New tests: exhaustion synthesis (mock LLM, nil session, empty conversation, cancelled ctx), fallback emission, replay pass-through/cache-hit/fingerprint-invalidation/error-not-cached, key determinism + fingerprint secrecy + file permissions
  • go build ./..., go vet, full engine + replaycache suites green
  • Boundary guard + govulncheck + full pre-push test suite green

@Patel230
Patel230 merged commit 931f863 into main Aug 24, 2026
26 checks passed
@Patel230
Patel230 deleted the feat/herm-followups branch August 24, 2026 10:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant