From 2ebc2afc6d8ecc95bb70a66faf73752249cc60df Mon Sep 17 00:00:00 2001
From: TZZheng <tzzheng1996@gmail.com>
Date: Sun, 12 Jul 2026 15:51:58 -0500
Subject: [PATCH] fix(meta): make helper type hints runtime-resolvable (#752)

---
 src/lingtai/kernel/meta_block.py |  4 ++--
 tests/test_meta_block.py         | 15 +++++++++++++++
 2 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/src/lingtai/kernel/meta_block.py b/src/lingtai/kernel/meta_block.py
index 4d198b40d..1e20a1779 100644
--- a/src/lingtai/kernel/meta_block.py
+++ b/src/lingtai/kernel/meta_block.py
@@ -53,7 +53,7 @@
 import time as _time
 import copy as _copy
 from collections.abc import Mapping
-from typing import NamedTuple
+from typing import Any, Dict, NamedTuple
 
 from .config import (
     CONTEXT_PRESSURE_HIGH_RATIO,
@@ -464,7 +464,7 @@ def static_adapter_comment(agent):
         return None
 
 
-def dynamic_adapter_comment(agent: AgentState) -> Mapping[str, Any] | None:
+def dynamic_adapter_comment(agent: object) -> Mapping[str, Any] | None:
     """Return adapter-owned dynamic tail state for ``_meta.agent_meta``.
 
     Adapters that can separate static guidance from dynamic runtime state should
diff --git a/tests/test_meta_block.py b/tests/test_meta_block.py
index 67f9e174e..ace7fdd54 100644
--- a/tests/test_meta_block.py
+++ b/tests/test_meta_block.py
@@ -4,6 +4,7 @@
 import json
 import re
 from types import SimpleNamespace
+from typing import get_type_hints
 
 import pytest
 import lingtai.kernel.meta_block as meta_block
@@ -37,6 +38,20 @@
 from lingtai.kernel.llm.interface import ToolResultBlock
 
 
+@pytest.mark.parametrize(
+    "helper",
+    [
+        dynamic_adapter_comment,
+        slim_adapter_comment_for_tail,
+        meta_block.build_meta_readme_section,
+        build_guidance_with_meta_readme,
+    ],
+)
+def test_helper_type_hints_are_runtime_resolvable(helper):
+    """Public helper annotations must resolve without caller-supplied globals."""
+    assert get_type_hints(helper)
+
+
 def _fake_agent(*, time_awareness: bool = True, timezone_awareness: bool = True):
     """Minimal agent stand-in: build_meta only reads agent._config.*."""
     return SimpleNamespace(