refactor(api): type tool parameter cache payload

[carlos4s]

Part of #34878

Summary

• add ToolParameterCachePayload in api/core/helper/tool_parameter_cache.py
• replace dict[str, Any] cache payloads with dict[str, object]
• update ToolParameterConfigurationManager to use the typed cache payload
• centralize secret-parameter string narrowing before masking, encryption, and decryption
• add explicit -> None return types for cache deletion helpers

Files changed

• api/core/helper/tool_parameter_cache.py
• api/core/tools/utils/configuration.py

[github-actions]

Pyrefly Diff

base → PR

--- /tmp/pyrefly_base.txt	2026-04-14 03:21:31.626514789 +0000
+++ /tmp/pyrefly_pr.txt	2026-04-14 03:21:21.619296709 +0000
@@ -3955,6 +3955,8 @@
   --> tests/unit_tests/core/external_data_tool/test_base.py:49:17
 ERROR Class member `ConcreteTool.query` overrides parent class `ExternalDataTool` in an inconsistent manner [bad-override]
   --> tests/unit_tests/core/external_data_tool/test_base.py:61:17
+ERROR Argument `dict[str, str]` is not assignable to parameter `parameters` with type `dict[str, object]` in function `core.helper.tool_parameter_cache.ToolParameterCache.set` [bad-argument-type]
+  --> tests/unit_tests/core/helper/test_tool_parameter_cache.py:67:15
 ERROR Argument `None` is not assignable to parameter `schema` with type `dict[Unknown, Unknown]` in function `core.llm_generator.output_parser.structured_output.remove_additional_properties` [bad-argument-type]
   --> tests/unit_tests/core/llm_generator/output_parser/test_structured_output.py:50:38
 ERROR Argument `list[@_]` is not assignable to parameter `schema` with type `dict[Unknown, Unknown]` in function `core.llm_generator.output_parser.structured_output.remove_additional_properties` [bad-argument-type]

[carlos4s]

Hi, @asukaminato0721
I am really sorry for many pings.
Can you review my PR as well as previous PRs (#35120 #34855)?
Thanks.

[asukaminato0721]

@dosu can we have a more precise type, like typeddict ?

[dosubot]

A TypedDict wouldn't be a great fit here unfortunately. The cached dictionary has dynamic, tool-dependent keys — the keys are parameter names that vary per tool, and the values are heterogeneous types (strings, numbers, etc.). Since the structure isn't known at type-checking time, TypedDict (which requires fixed, statically-known keys) can't really express this [1] [2].

dict[str, Any] is essentially the correct type for this kind of runtime-dynamic, arbitrary key-value data. If you wanted slightly more precision, you could narrow the value type to dict[str, str | int | float | bool | None] if those are the only parameter value types that actually appear, but that depends on whether tool parameters are always primitives.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}