agentengine-sdk-python 0.8.0__py3-none-any.whl → 0.8.2__py3-none-any.whl

ksadk/memory/service.py

@@ -8,15 +8,25 @@ import os
 from typing import Any, cast
 
 from ksadk.common.aicp_env import resolve_aicp_connection
-from ksadk.memory.adk.backends.base_ltm_backend import BaseLongTermMemoryBackend
+from ksadk.memory.adk.backends.base_ltm_backend import (
+    CAP_SESSION_STATUS,
+    CAP_STRUCTURED_SEARCH,
+    BaseLongTermMemoryBackend,
+)
 from ksadk.memory.ltm_backend_factory import get_long_term_memory_backend_cls
+from ksadk.memory.models import (
+    LongTermMemoryRecord,
+    MemoryExtractionStatus,
+    MemoryMutationResult,
+    UnsupportedMemoryOperation,
+)
 
 logger = logging.getLogger(__name__)
 
 
 def format_memory_entries(entries: list[str]) -> str:
     if not entries:
-        return "未找到相关长期记忆。"
+        return ""  # empty → "" not "未找到"（§10.8）
 
     formatted_entries: list[str] = []
     for index, entry in enumerate(entries, 1):
@@ -35,6 +45,11 @@ def format_memory_entries(entries: list[str]) -> str:
     return "\n\n".join(formatted_entries)
 
 
+def _normalize_content(text: str) -> str:
+    """归一化正文，用于写后确认的可见性匹配（去空白，小写）。"""
+    return "".join(str(text or "").split()).lower()
+
+
 class LongTermMemoryService:
     def __init__(
         self,
@@ -77,10 +92,18 @@ class LongTermMemoryService:
             connection = resolve_aicp_connection("KSADK_LTM")
             backend_config = {
                 "access_key": (
-                    os.environ.get("KSADK_LTM_ACCESS_KEY") or os.environ.get("KSYUN_ACCESS_KEY", "")
+                    os.environ.get("KSADK_LTM_ACCESS_KEY")
+                    or os.environ.get("KSYUN_ACCESS_KEY")
+                    or os.environ.get("KSYUN_ACCESS_KEY_ID", "")
                 ),
                 "secret_key": (
-                    os.environ.get("KSADK_LTM_SECRET_KEY") or os.environ.get("KSYUN_SECRET_KEY", "")
+                    os.environ.get("KSADK_LTM_SECRET_KEY")
+                    or os.environ.get("KSYUN_SECRET_KEY")
+                    or os.environ.get("KSYUN_SECRET_ACCESS_KEY", "")
+                ),
+                "session_token": (
+                    os.environ.get("KSADK_LTM_SESSION_TOKEN")
+                    or os.environ.get("KSYUN_SESSION_TOKEN", "")
                 ),
                 "region": connection["region"],
                 "endpoint": connection["endpoint"],
@@ -118,14 +141,137 @@ class LongTermMemoryService:
             top_k=top_k if top_k is not None else self.top_k,
         )
 
+    def search_records(
+        self, *, user_id: str, query: str, top_k: int | None = None
+    ) -> list[LongTermMemoryRecord]:
+        """结构化检索（§7.5）：优先走 backend.search_records，返回带服务端 ID 的记录。
+
+        旧 backend 不支持时抛出 UnsupportedMemoryOperation，
+        由上层降级为只读 search/add，不得伪造 ID。
+        """
+        return self._backend.search_records(
+            user_id=user_id,
+            query=query,
+            top_k=top_k if top_k is not None else self.top_k,
+        )
+
+    def update_memory(
+        self,
+        *,
+        user_id: str,
+        memory_id: str,
+        content: str,
+    ) -> MemoryMutationResult:
+        """按 ID 原地更新记忆（§7.4）；不支持的 backend 抛稳定异常。"""
+        return self._backend.update_memory(
+            user_id=user_id,
+            memory_id=memory_id,
+            content=content,
+        )
+
+    def delete_memory(self, *, user_id: str, memory_id: str) -> MemoryMutationResult:
+        """按 ID 软删除记忆（§7.4）；重复删除归一为 already_absent。"""
+        return self._backend.delete_memory(user_id=user_id, memory_id=memory_id)
+
+    def list_memory_records(
+        self,
+        *,
+        user_id: str,
+        query: str = "",
+        page: int = 1,
+        page_size: int = 20,
+    ) -> list[LongTermMemoryRecord]:
+        """ListMemories 透传：写后确认可见性 / 取当前 MemoryId。"""
+        return self._backend.list_memory_records(
+            user_id=user_id, query=query, page=page, page_size=page_size
+        )
+
+    def get_extraction_status(
+        self,
+        *,
+        user_id: str,
+        session_id: str,
+        confirm_searchable: bool = False,
+        expected_content: str = "",
+    ) -> MemoryExtractionStatus:
+        """写后确认（§7.7）：查询 Session 后台提取状态。
+
+        Args:
+            confirm_searchable: True 且 State=100 时，进一步通过
+                ListMemories 确认目标记录可见（目标达成后 searchable=True）。
+            expected_content: 用于在 ListMemories 中定位目标记录的归一化正文。
+        """
+        if CAP_SESSION_STATUS not in self._backend.capabilities():
+            raise UnsupportedMemoryOperation(
+                f"{type(self._backend).__name__} does not support session status"
+            )
+        status = self._backend.get_extraction_status(user_id=user_id, session_id=session_id)
+        if (
+            confirm_searchable
+            and status.status == "extracted"
+            and CAP_STRUCTURED_SEARCH in self._backend.capabilities()
+            and expected_content.strip()
+        ):
+            # 用 expected_content 作为 Query 语义过滤，避免大记忆库时目标不在首页。
+            records = self.list_memory_records(
+                user_id=user_id, query=expected_content, page_size=50
+            )
+            if self._find_matching_record(records, expected_content) is not None:
+                status = MemoryExtractionStatus(
+                    session_id=status.session_id,
+                    state=status.state,
+                    status=status.status,
+                    searchable=True,
+                    message=status.message,
+                )
+        return status
+
+    @staticmethod
+    def _find_matching_record(
+        records: list[LongTermMemoryRecord], expected_content: str
+    ) -> LongTermMemoryRecord | None:
+        """按归一化正文等值/包含匹配目标记录（方案 N3：可见性判定规则）。
+
+        expected_content 为空时不作匹配（返回 None），避免误判任意记录为可见。
+        """
+        normalized = _normalize_content(expected_content)
+        if not normalized:
+            return None
+        for record in records:
+            if normalized == _normalize_content(record.content):
+                return record
+        for record in records:
+            if normalized in _normalize_content(record.content):
+                return record
+        return None
+
+    def capabilities(self) -> set[str]:
+        """透传 backend 能力声明（§7.3）。"""
+        return set(self._backend.capabilities())
+
+    @property
+    def last_error(self) -> str:
+        """最近一次后端失败原因（成功调用前置空，失败时填充）。
+
+        后端（SDK/HTTP）失败时可能吞掉异常返空列表而非抛错，这里把该信号暴露给
+        ``build_context``，以区分"后端吞错返空"与"真无记忆"。
+        """
+        return str(getattr(self._backend, "last_error", "") or "")
+
     def search_text(self, *, user_id: str, query: str, top_k: int | None = None) -> str:
+        """检索长期记忆并格式化为文本（方案 §10.8：错误不得混入正文）。
+
+        Provider 异常时返回空字符串而非错误文本——错误文本会被当作记忆正文注入模型上下文，
+        污染回答。需要区分"真无记忆"与"后端失败"的调用方应改用 ``build_context()``
+        或检查 ``self.last_error``。
+        """
         try:
             return format_memory_entries(
                 self.search_entries(user_id=user_id, query=query, top_k=top_k)
             )
         except Exception as exc:
             logger.error("load_memory failed: %s", exc)
-            return f"长期记忆检索失败: {exc}"
+            return ""
 
     def save_event_strings(
         self,
@@ -133,18 +279,52 @@ class LongTermMemoryService:
         user_id: str,
         event_strings: list[str],
         metadata: dict[str, Any] | None = None,
+        session_id: str | None = None,
+        flush: bool | None = None,
     ) -> bool:
+        """保存事件字符串。
+
+        显式参数优先于 metadata（方案 §7.6）：
+            flush: None 表示未指定，回退到 metadata["flush"]；
+                True/False 显式覆盖 metadata。
+            session_id: None 回退到 metadata["session_id"]。
+        兼容期旧调用（仅 metadata）行为不变。
+        """
+        base_metadata = dict(metadata or {})
+        effective_flush = flush if flush is not None else base_metadata.get("flush")
+        if session_id is not None:
+            base_metadata["session_id"] = session_id
+        effective_session_id = base_metadata.get("session_id")
+        # 只有显式为 True 时才携带 flush；False/未携带时不传，
+        # 让服务端走默认累积策略（§5.2）。
+        if effective_flush is True:
+            base_metadata["flush"] = True
+        else:
+            base_metadata.pop("flush", None)
         return bool(
             self._backend.save_memory(
                 user_id=user_id,
                 event_strings=event_strings,
-                metadata=metadata or {},
+                metadata=base_metadata,
+                session_id=effective_session_id,
+                flush=effective_flush,
             )
         )
 
     def save_text(
-        self, *, user_id: str, content: str, metadata: dict[str, Any] | None = None
+        self,
+        *,
+        user_id: str,
+        content: str,
+        metadata: dict[str, Any] | None = None,
+        session_id: str | None = None,
+        flush: bool | None = None,
     ) -> bool:
+        """保存自包含事实文本。
+
+        显式 flush=True 用于显式、内容自包含的持久事实保存
+        （如 ksadk_memory_add）；普通 sync_turn 不传 flush（§3.1/§8.7）。
+        """
         payload = {
             "role": "user",
             "parts": [{"text": content}],
@@ -154,6 +334,8 @@ class LongTermMemoryService:
             user_id=user_id,
             event_strings=[json.dumps(payload, ensure_ascii=False)],
             metadata=metadata,
+            session_id=session_id,
+            flush=flush,
         )
 
     def build_context(
@@ -168,7 +350,15 @@ class LongTermMemoryService:
             return None
         if not self.is_configured():
             return None
+        try:
+            entries = self.search_entries(user_id=user_id, query=normalized, top_k=top_k)
+        except Exception as exc:
+            logger.error("load_memory failed: %s", exc)
+            return {"query": normalized, "formatted_text": "", "error": str(exc)}
+        backend_error = self.last_error
+        if not entries and backend_error:
+            return {"query": normalized, "formatted_text": "", "error": backend_error}
         return {
             "query": normalized,
-            "formatted_text": self.search_text(user_id=user_id, query=normalized, top_k=top_k),
+            "formatted_text": format_memory_entries(entries),
         }

ksadk/memory/tool.py

@@ -78,6 +78,10 @@ def save_memory(content: str) -> dict:
                 "agent_id": context.agent_id,
                 "session_id": context.session_id,
                 "runner_type": context.runner_type,
+                # Explicit user saves must become searchable promptly. The
+                # SDK backend maps this to CreateMemorySdk.Flush; background
+                # turn persistence keeps the service's batched default.
+                "flush": True,
             },
         )
         if ok:

ksadk/model_proxy/bootstrap.py

@@ -21,6 +21,7 @@ from .server import ProxyServer
 # 进程级单例:setup_environment 多次调用只起一个 proxy
 _proxy: Optional[ProxyServer] = None
 _original_base: Optional[str] = None
+_original_base_env: Optional[dict[str, str | None]] = None
 
 
 def setup_proxy_redirect_if_enabled(
@@ -35,7 +36,7 @@ def setup_proxy_redirect_if_enabled(
     返回 proxy base_url(已重定向)或 None(未启用)。多次调用幂等(单例)。
     上游凭证来自 ProxyConfig(从 env 读),不下发给子进程(凭证闭合)。
     """
-    global _proxy, _original_base
+    global _proxy, _original_base, _original_base_env
     if _proxy is not None:
         return _proxy.base_url  # 幂等:已起
     gate = gate or ProxyGate.from_env()
@@ -48,9 +49,7 @@ def setup_proxy_redirect_if_enabled(
         or os.environ.get("OPENAI_API_BASE")
         or ""
     )
-    key = (
-        api_key or os.environ.get("OPENAI_API_KEY") or os.environ.get("LLM_API_KEY") or ""
-    )
+    key = api_key or os.environ.get("OPENAI_API_KEY") or os.environ.get("LLM_API_KEY") or ""
     token = local_token or os.environ.get("KSADK_PROXY_TOKEN") or ""
     if not upstream or not key:
         return None  # 缺凭证/上游,不启用(保持原 env)
@@ -59,7 +58,11 @@ def setup_proxy_redirect_if_enabled(
     srv.start()
     _proxy = srv
     # 记录原 base 并重定向(双别名都指向 proxy)
-    _original_base = os.environ.get("OPENAI_BASE_URL") or os.environ.get("OPENAI_API_BASE")
+    _original_base_env = {
+        "OPENAI_BASE_URL": os.environ.get("OPENAI_BASE_URL"),
+        "OPENAI_API_BASE": os.environ.get("OPENAI_API_BASE"),
+    }
+    _original_base = _original_base_env["OPENAI_BASE_URL"] or _original_base_env["OPENAI_API_BASE"]
     os.environ["OPENAI_BASE_URL"] = srv.base_url
     os.environ["OPENAI_API_BASE"] = srv.base_url
     if not token:
@@ -70,11 +73,15 @@ def setup_proxy_redirect_if_enabled(
 
 def teardown_proxy_redirect() -> None:
     """回收 proxy 并恢复原 OPENAI_BASE_URL(进程退出/卸载时调)。"""
-    global _proxy, _original_base
+    global _proxy, _original_base, _original_base_env
     if _proxy is not None:
         _proxy.stop()
         _proxy = None
-    if _original_base is not None:
-        os.environ["OPENAI_BASE_URL"] = _original_base
-        os.environ["OPENAI_API_BASE"] = _original_base
+    if _original_base_env is not None:
+        for key, value in _original_base_env.items():
+            if value is None:
+                os.environ.pop(key, None)
+            else:
+                os.environ[key] = value
+        _original_base_env = None
         _original_base = None

ksadk/model_proxy/config.py

@@ -1,7 +1,8 @@
 """ProxyConfig:转换 proxy 的配置(显式注入,不在模块导入时读 env,便于内化与测试)。"""
 
 import os
-from dataclasses import dataclass
+from dataclasses import dataclass, field
+from typing import Any, Callable
 from urllib.parse import urlsplit
 
 # HTTPS(凭证安全):不再用明文 HTTP 携带 Bearer key。
@@ -15,17 +16,37 @@ class ProxyConfig:
     upstream_base: str = DEFAULT_UPSTREAM_BASE
     api_key: str = ""  # 上游凭证(proxy -> 上游)
     local_token: str = ""  # 本地 proxy 鉴权 token(codex -> proxy);空则不校验(仅本地调试)
+    # 非空时 responses 转换路径强制改写 model（Codex 可能发送内部伪模型名）。
+    upstream_model: str = ""
     timeout: float = 180.0
+    event_callback: Callable[[str, dict[str, Any]], None] | None = field(
+        default=None,
+        repr=False,
+        compare=False,
+    )
 
     def __post_init__(self) -> None:
         self.upstream_base = _require_secure_upstream(self.upstream_base.rstrip("/"))
 
+    def emit(self, event: str, data: dict[str, Any]) -> None:
+        callback = self.event_callback
+        if callback is None:
+            return
+        try:
+            callback(event, data)
+        except Exception:
+            # Observability must never break model traffic.
+            return
+
     @classmethod
     def from_env(cls) -> "ProxyConfig":
         return cls(
             upstream_base=os.environ.get("UPSTREAM_BASE", DEFAULT_UPSTREAM_BASE),
             api_key=os.environ.get("KSPMAS_API_KEY", ""),
             local_token=os.environ.get("KSADK_PROXY_TOKEN", ""),
+            upstream_model=os.environ.get("OPENAI_MODEL_NAME")
+            or os.environ.get("MODEL_NAME")
+            or "",
             timeout=float(os.environ.get("UPSTREAM_TIMEOUT", "180")),
         )
 

ksadk/model_proxy/detect.py

@@ -12,6 +12,9 @@
   超时/5xx/429/401/403 一律 "unknown",不改变判定(故障 ≠ 能力缺失)。
 - ``stream_delta_ok`` 需真发流式请求才能判定,成本高,本模块默认 None(不探),
   由调用方按需触发或默认走转换层(转换层自己生成完整 delta)。
+- Codex 直连还需功能性 tool probes:真实发送当前 Codex 会声明的
+  ``additional_tools`` 工具面。任一必需类型被拒时保留
+  ``responses_supported=True``,同时推荐经 Chat 转换层执行。
 """
 
 from __future__ import annotations
@@ -24,6 +27,12 @@ import httpx
 
 Verdict = Literal["supported", "unsupported", "unknown"]
 
+# These are Codex wire-contract capabilities, not provider/model allowlists.
+# namespace/custom are required for a native Responses turn; web_search is an
+# optional built-in that may be disabled without downgrading the whole protocol.
+CODEX_DIRECT_REQUIRED_TOOL_TYPES = frozenset({"namespace", "custom"})
+CODEX_OPTIONAL_TOOL_TYPES = frozenset({"web_search"})
+
 
 @dataclass
 class ModelCapabilities:
@@ -31,7 +40,7 @@ class ModelCapabilities:
 
     responses_supported: bool | None = None  # None = 未知(未探/不确定)
     stream_delta_ok: bool | None = None  # 流式增量 delta;None = 未探
-    tool_types: set[str] = field(default_factory=set)  # 支持的工具 namespace
+    tool_types: set[str] = field(default_factory=set)  # 已实测支持的 Codex 工具类型
     preferred_protocol: str = "chat"  # "responses" | "chat":路由该走哪条
     checked_at: float = 0.0
     verdict: Verdict = "unknown"  # 最近一次探测结论
@@ -65,7 +74,10 @@ def probe_responses_capability(
 ):
     """功能性 probe /v1/responses,返回能力矩阵(sync) 或 coroutine(async)。
 
-    - 200 且结构合法(output+status)→ supported,preferred_protocol=responses
+    - 纯文本 200 且结构合法后，再逐个探测真实 Codex 工具类型
+    - namespace/custom 成功→ preferred_protocol=responses
+    - 仅 web_search 被拒→仍为 responses，但不把 web_search 记入 tool_types
+    - namespace/custom 被拒→ supported,preferred_protocol=chat
     - 200 但非 responses 结构(网关伪 200)→ unsupported,preferred_protocol=chat
     - 404/405/400 unknown → unsupported,preferred_protocol=chat
     - 超时/5xx/429/401/403 → unknown,preferred_protocol 保持默认 chat(保守走转换层)
@@ -86,16 +98,47 @@ def _probe_sync(
     caps = ModelCapabilities(checked_at=time.time(), verdict="unknown")
     url = f"{base.rstrip('/')}/responses"
     headers = {"Authorization": f"Bearer {key}", "Content-Type": "application/json"}
-    payload = {"model": model, "input": "hi", "max_output_tokens": 1, "stream": False}
     try:
-        r = client.post(url, json=payload, headers=headers, timeout=timeout)
+        r = client.post(
+            url,
+            json=_base_probe_payload(model),
+            headers=headers,
+            timeout=timeout,
+        )
     except (httpx.TimeoutException, httpx.ConnectError, httpx.HTTPError):
         return _finalize(caps)
     try:
         data = r.json()
     except ValueError:
         data = None
-    return _apply_response(caps, r.status_code, r.text, data)
+    caps = _apply_response(caps, r.status_code, r.text, data)
+    if not caps.responses_supported:
+        return caps
+    for tool_type, payload in _codex_tool_probe_payloads(model):
+        try:
+            tool_response = client.post(
+                url,
+                json=payload,
+                headers=headers,
+                timeout=timeout,
+            )
+        except (httpx.TimeoutException, httpx.ConnectError, httpx.HTTPError):
+            caps.verdict = "unknown"
+            return _finalize(caps)
+        try:
+            tool_data = tool_response.json()
+        except ValueError:
+            tool_data = None
+        caps = _apply_tool_response(
+            caps,
+            tool_type,
+            tool_response.status_code,
+            tool_response.text,
+            tool_data,
+        )
+        if tool_type not in caps.tool_types:
+            return caps
+    return _finalize(caps)
 
 
 async def _probe_async(
@@ -104,16 +147,162 @@ async def _probe_async(
     caps = ModelCapabilities(checked_at=time.time(), verdict="unknown")
     url = f"{base.rstrip('/')}/responses"
     headers = {"Authorization": f"Bearer {key}", "Content-Type": "application/json"}
-    payload = {"model": model, "input": "hi", "max_output_tokens": 1, "stream": False}
     try:
-        r = await client.post(url, json=payload, headers=headers, timeout=timeout)
+        r = await client.post(
+            url,
+            json=_base_probe_payload(model),
+            headers=headers,
+            timeout=timeout,
+        )
     except (httpx.TimeoutException, httpx.ConnectError, httpx.HTTPError):
         return _finalize(caps)
     try:
         data = r.json()
     except ValueError:
         data = None
-    return _apply_response(caps, r.status_code, r.text, data)
+    caps = _apply_response(caps, r.status_code, r.text, data)
+    if not caps.responses_supported:
+        return caps
+    for tool_type, payload in _codex_tool_probe_payloads(model):
+        try:
+            tool_response = await client.post(
+                url,
+                json=payload,
+                headers=headers,
+                timeout=timeout,
+            )
+        except (httpx.TimeoutException, httpx.ConnectError, httpx.HTTPError):
+            caps.verdict = "unknown"
+            return _finalize(caps)
+        try:
+            tool_data = tool_response.json()
+        except ValueError:
+            tool_data = None
+        caps = _apply_tool_response(
+            caps,
+            tool_type,
+            tool_response.status_code,
+            tool_response.text,
+            tool_data,
+        )
+        if tool_type not in caps.tool_types:
+            return caps
+    return _finalize(caps)
+
+
+def _base_probe_payload(model: str) -> dict[str, Any]:
+    return {"model": model, "input": "hi", "max_output_tokens": 1, "stream": False}
+
+
+def _namespace_probe_payload(model: str) -> dict[str, Any]:
+    """Return the smallest real Codex 0.147 dynamic-tool declaration."""
+
+    return {
+        "model": model,
+        "input": [
+            {
+                "type": "additional_tools",
+                "role": "developer",
+                "tools": [
+                    {
+                        "type": "namespace",
+                        "name": "functions",
+                        "description": "KsADK Codex capability probe",
+                        "tools": [
+                            {
+                                "type": "function",
+                                "name": "probe",
+                                "description": "Probe Codex namespace tool support",
+                                "parameters": {
+                                    "type": "object",
+                                    "properties": {},
+                                    "additionalProperties": False,
+                                },
+                            }
+                        ],
+                    }
+                ],
+            },
+            {
+                "type": "message",
+                "role": "user",
+                "content": [{"type": "input_text", "text": "Reply with OK."}],
+            },
+        ],
+        "max_output_tokens": 1,
+        "stream": False,
+    }
+
+
+def _custom_probe_payload(model: str) -> dict[str, Any]:
+    """Return the smallest Codex namespaced freeform-tool declaration."""
+
+    payload = _namespace_probe_payload(model)
+    payload["input"][0]["tools"][0]["tools"] = [
+        {
+            "type": "custom",
+            "name": "probe",
+            "description": "Probe Codex custom tool support",
+            "format": {
+                "type": "grammar",
+                "syntax": "lark",
+                "definition": 'start: "OK"',
+            },
+        }
+    ]
+    return payload
+
+
+def _web_search_probe_payload(model: str) -> dict[str, Any]:
+    """Return Codex's ``additional_tools`` built-in web-search declaration."""
+
+    payload = _namespace_probe_payload(model)
+    payload["input"][0]["tools"] = [{"type": "web_search"}]
+    return payload
+
+
+def _codex_tool_probe_payloads(model: str) -> tuple[tuple[str, dict[str, Any]], ...]:
+    """Return the model-agnostic direct tool surface required by Codex."""
+
+    return (
+        ("namespace", _namespace_probe_payload(model)),
+        ("custom", _custom_probe_payload(model)),
+        ("web_search", _web_search_probe_payload(model)),
+    )
+
+
+def _apply_tool_response(
+    caps: ModelCapabilities, tool_type: str, status: int, text: str, data: Any
+) -> ModelCapabilities:
+    valid_envelope = isinstance(data, dict) and "output" in data and "status" in data
+    envelope_failed = valid_envelope and (
+        str(data.get("status") or "").lower() == "failed" or bool(data.get("error"))
+    )
+    if status == 200 and valid_envelope and not envelope_failed:
+        caps.tool_types.add(tool_type)
+        caps.verdict = "supported"
+        return _finalize(caps)
+
+    low = (text or "").lower()
+    dialect_marker = any(
+        marker in low
+        for marker in (
+            tool_type.lower(),
+            "additional_tools",
+            "invalid value",
+            "supported values",
+            "not supported",
+            "unrecognized",
+        )
+    )
+    dialect_rejected = (
+        status in (400, 404, 405, 422) and (status in (404, 405) or dialect_marker)
+    ) or (status == 200 and envelope_failed and dialect_marker)
+    if not dialect_rejected:
+        # Transient failures do not establish direct compatibility and should
+        # not be cached as a native Codex tool-capable endpoint.
+        caps.verdict = "unknown"
+    return _finalize(caps)
 
 
 def _apply_response(
@@ -136,7 +325,11 @@ def _apply_response(
 
 def _finalize(caps: ModelCapabilities) -> ModelCapabilities:
     """根据 verdict 定 preferred_protocol(保守:不确定也走转换层 chat)。"""
-    if caps.verdict == "supported" and caps.responses_supported:
+    if (
+        caps.verdict == "supported"
+        and caps.responses_supported
+        and CODEX_DIRECT_REQUIRED_TOOL_TYPES.issubset(caps.tool_types)
+    ):
         caps.preferred_protocol = "responses"
     else:
         # unsupported 或 unknown 都默认 chat(走转换层):unknown 时走转换层更安全,