Files
docker-agent/pkg/cache
David Gageot 808323635c docs(cache): document invariants surfaced by review; add edge-case tests
Targeted follow-ups from a second-pass review. No behavior change for
existing scenarios; the only functional delta is that
after_llm_call hooks now also receive AgentName / LastUserMessage,
matching what the field's doc comment already promised.

Bug fixes / contract tightening:

- pkg/runtime/runtime.go: populate AgentName and LastUserMessage in
  executeAfterLLMCallHooks, not just executeStopHooks. The Input doc
  comment listed both events; this finishes the implementation.
- pkg/runtime/cache.go: log a Debug line in cacheResponseBuiltin when
  team.Agent(in.AgentName) fails so a misconfigured team is at least
  visible in --debug output instead of silently dropping the write.

Comments to prevent future regressions:

- pkg/cache/cache.go: Store now explicitly documents WHY the persist
  callback runs under the write lock. Releasing the lock between
  cloning the snapshot and writing it would let two concurrent stores
  persist out-of-order and silently overwrite a newer entry with an
  older snapshot on the next restart — exactly the lost-write race
  fixed in 73d806943. The comment makes the trade-off (brief read
  latency vs. strict serialization) the deliberate choice it is.
- pkg/runtime/cache.go: explain why tryReplayCachedResponse treats an
  empty cached value as a miss instead of replaying it.
- pkg/cache/cache.go: document the trim-then-lowercase order in
  keyNormalizer so a future change doesn't accidentally swap them.

Tests:

- pkg/cache/cache_test.go::TestFileCache_persistenceFailureKeepsInMemory
  pins the invariant that a write failure (here: cache directory
  stripped of write permission after New) does not break Store —
  the in-memory map still receives the entry, only the disk mirror
  is skipped. Skipped when running as root.
- pkg/runtime/cache_test.go::TestCache_EmptyResponseIsNotCached pins
  the empty-response semantics: an empty assistant content is dropped
  from the cache and the model is consulted on every repeat ask.

Validation: mise lint clean, full mise test green,
go test -race ./pkg/cache/... ./pkg/runtime/ ./pkg/teamloader/ clean.

Assisted-By: docker-agent
2026-04-28 09:23:27 +02:00
..