fix: inject available cache_uri hints into MCP tool error envelopes

CHANGELOG.md

@@ -8,6 +8,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.16.1-beta.0] — 2026-05-28
+
+### Added
+
+- **`available_cache_uris` field on MCP tool error envelopes** (plan `docs/plans/2026-05-28-003-fix-error-envelope-cache-uri-hint-plan.md`). When an MCP tool returns an `{error: "<string>"}` envelope (engine-side inline-list cap OR MCP-server-side validation), the engine scans the last 10 `role: "tool"` messages backward, harvests `_cache_uri` per upstream tool name (deduped, most-recent-first), and appends `available_cache_uris: [{tool_name, cache_uri}, ...]` to the LLM-visible envelope before pushing into conversation history. Fixes the observed underperformance where a failed `create_*` tool would cause the LLM to re-run the upstream data query — small / quantized models reliably drop `_cache_uri` values from attention by the time they see a chart-tool failure, so they defend by re-querying instead of reusing the cached pointer. With the new field, the URI lives in immediate error-envelope context.
+
+  - Wired at the inline-list-cap site (`engine/index.js:934`) and the dispatch path (`:1270`). Runs BEFORE the truncation block so oversized error envelopes preserve the field through the summary build (`:1257-1264`).
+  - NOT wired at the cache-miss site (`:957`) — that envelope already names the failing URIs verbatim via `_missing_uris`; enrichment would surface peer rows likely close to eviction.
+  - Short-circuits when `cacheOptions.enabled !== true` (the URI cannot exist) or when the envelope isn't an error. Additive only — existing `error`, `fix_hint`, `expected_kwargs`, `details`, `_engine_dispatched`, `_cache_uri` fields are preserved unchanged.
+  - Helper `enrichErrorEnvelope(envelope, messages, cacheOptions)` is exported from `engine/index.js` and re-exported via `engine/__test_internals__.js`.
+
 ## [0.16.0-beta.0] — 2026-05-28
 
 ### Added

engine/__test_internals__.js

@@ -16,4 +16,5 @@ export {
   discoverPrompts,
   getPrompt,
   EmptyPromptError,
+  enrichErrorEnvelope,
 } from "./index.js";