fix(hermes): pass retain_async=True to aretain_batch in tool handler

[yingliang-zhang]

Problem

The hindsight_retain tool handler called self._retain_batch(item, bank_id=self._bank_id) without forwarding the configured self._retain_async, so tool-initiated retains silently dropped the provider's async/sync choice — aretain_batch fell back to its own server default. retain_async is a call-level arg (never an item key — _retain_batch's contract), so the tool handler must pass it explicitly; the auto-retain path (_make_turn_retain_job → _retain_batch) already does.

Concretely: a user with retain_async: false got synchronous semantics for auto-retains but server-default semantics for tool retains — and on banks with significant data the LLM fact-extraction call can take 60–600+ s, far exceeding the 120 s default timeout, surfacing as an opaque TimeoutError ("Failed to store memory: "). With the flag forwarded, retain_async: true tool retains return as soon as the server accepts the request, matching sync_turn.

Fix

Forward the configured mode as a call argument, matching the auto-retain path:

self._retain_batch(item, bank_id=self._bank_id, retain_async=self._retain_async)

This preserves the review feedback applied on the original PR (pass the captured self._retain_async, not a hard-coded True, so an explicit retain_async: false is honored on both paths).

Tests

tests/test_retain_async_forwarding.py — test_retain_tool_forwards_configured_retain_async, parametrized over True/False, asserting the call-level retain_async matches the provider config (port of the original parameterized test, adapted to this tree's recording FakeClient).

Verification

uv run pytest tests/test_retain_async_forwarding.py -v (only the touched test file):

collecting ... collected 2 items

tests/test_retain_async_forwarding.py::test_retain_tool_forwards_configured_retain_async[True] PASSED [ 50%]
tests/test_retain_async_forwarding.py::test_retain_tool_forwards_configured_retain_async[False] PASSED [100%]

============================== 2 passed in 0.05s ===============================

Mutation check — reverting the one-line fix makes both cases RED:

FAILED tests/test_retain_async_forwarding.py::test_retain_tool_forwards_configured_retain_async[True] - KeyError: 'retain_async'
FAILED tests/test_retain_async_forwarding.py::test_retain_tool_forwards_configured_retain_async[False] - KeyError: 'retain_async'
============================== 2 failed in 0.09s ===============================

uv run pytest tests/test_provider.py (existing suite exercising the touched path, unchanged): 15 passed in 0.28s.

Provenance

Ported from NousResearch/hermes-agent#60648 (closed in the hindsight-move close pass; the bundled provider moved to hindsight-integrations/hermes in NousResearch/hermes-agent#119888). Original fix and analysis by @yingliang-zhang; review feedback by @teknium1 (configured value instead of hard-coded True, parameterized coverage) is incorporated. Tracked in #4662.

Stacked PR (pre-chained 2026-09-30): the diff vs main is cumulative with #4674; this PR's own change is forwarding the configured retain_async to aretain_batch in the hindsight_retain tool handler. Merge top-down: 4674 -> 4671 -> 4672 -> 4673 -> 4675 -> 4676. Identical shared commits merge cleanly in any order (git dedups same-patch-both-sides).

[yingliang-zhang]

CI note: verify-generated-files fails here for a pre-existing reason — ./scripts/generate-docs-skill.sh on a clean upstream/main (7a593e8) reproduces the same skills/hindsight-docs/references/developer/oracle.md drift, so the gate is red on every PR including unmodified main. Fixed by #4678 (single-file regeneration); once it merges, this PR's gate goes green with no changes needed here.

[yingliang-zhang]

Generated-files sync commit added atop the substantive commit(s): the verify-generated-files gate runs its generators against the PR head (actions/checkout at ref: head.sha), so this branch now carries its own regenerated skills/hindsight-docs/references/developer/oracle.md plus the lint.sh ruff formatting, committed as chore: sync generated files for verify-generated-files. No substantive changes — the review surface is exactly as before.

[nicoloboschi]

Thanks for this! We're tracking this problem in #4662 and will fix it from there, so I'm closing this PR.

We've stopped accepting pull requests from outside the team (see CONTRIBUTING.md). Any extra detail or steps to reproduce on the issue are very welcome.