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

ksadk/conversations/__init__.py

@@ -1,5 +1,10 @@
 from __future__ import annotations
 
+from ksadk.conversations.attachments import (
+    decode_inline_data,
+    resolve_attachment_storage_path,
+    resolve_uploads_dir,
+)
 from ksadk.conversations.context import (
     CANONICAL_EVENT_TYPES,
     build_history_from_events,
@@ -16,21 +21,18 @@ from ksadk.conversations.normalize import (
     attachment_from_part,
     attachment_prompt_text,
     compact_attachment_for_session,
-    decode_inline_data,
     display_content_from_parts,
     extract_user_input_from_parts,
     normalize_kop_message_content,
     normalize_kop_messages,
     normalize_parts_content,
     normalize_responses_input,
-    resolve_attachment_storage_path,
-    resolve_uploads_dir,
 )
 from ksadk.conversations.runtime import (
     CompactionPlan,
     PreparedConversationTurn,
-    append_conversation_event,
     append_context_checkpoint_event,
+    append_conversation_event,
     append_reasoning_event,
     append_run_checkpoint_event,
     append_run_resume_event,
@@ -43,8 +45,8 @@ from ksadk.conversations.runtime import (
     ensure_conversation_session,
     extract_responses_resume_input,
     invoke_conversation_once,
-    prime_session_metadata_for_user_turn,
     preview_auto_compaction,
+    prime_session_metadata_for_user_turn,
     stream_conversation_turn,
     stream_responses_conversation_turn,
 )

ksadk/conversations/attachment_storage.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import asyncio
+import importlib
 import json
 import logging
 import mimetypes
@@ -81,8 +82,7 @@ def _download_hosted_attachment(file_uri: str) -> AttachmentBytes | None:
         data=content.data,
         display_name=display_name,
         mime_type=(
-            _content_type_without_params(content.content_type)
-            or guess_mime_type(display_name)
+            _content_type_without_params(content.content_type) or guess_mime_type(display_name)
         ),
     )
 
@@ -222,7 +222,9 @@ class AttachmentStorageService:
                     return AttachmentBytes(
                         data=raw,
                         display_name=str(metadata.get("display_name") or local_path.name),
-                        mime_type=str(metadata.get("mime_type") or guess_mime_type(local_path.name)),
+                        mime_type=str(
+                            metadata.get("mime_type") or guess_mime_type(local_path.name)
+                        ),
                         local_path=local_path,
                     )
 
@@ -272,16 +274,17 @@ class AttachmentStorageService:
     async def _read_ks3_object(self, *, bucket: str, object_key: str) -> bytes:
         return await asyncio.to_thread(self._read_ks3_object_sync, bucket, object_key)
 
-    def _put_ks3_object_sync(self, bucket: str, object_key: str, data: bytes, mime_type: str) -> None:
+    def _put_ks3_object_sync(
+        self, bucket: str, object_key: str, data: bytes, mime_type: str
+    ) -> None:
         if not bucket:
             raise ValueError("KS3 bucket is not available")
-        from ks3.connection import Connection
-
         ak = os.getenv("KSYUN_ACCESS_KEY") or os.getenv("KS3_ACCESS_KEY")
         sk = os.getenv("KSYUN_SECRET_KEY") or os.getenv("KS3_SECRET_KEY")
         if not ak or not sk:
             raise ValueError("KS3 credentials are not configured")
-        conn = Connection(ak, sk, host=self._endpoint())
+        connection_class = importlib.import_module("ks3.connection").Connection
+        conn = connection_class(ak, sk, host=self._endpoint())
         ks3_bucket = self._ensure_bucket(conn, bucket)
         key = ks3_bucket.new_key(object_key)
         key.set_contents_from_string(
@@ -292,17 +295,19 @@ class AttachmentStorageService:
     def _read_ks3_object_sync(self, bucket: str, object_key: str) -> bytes:
         if not bucket or not object_key:
             raise FileNotFoundError(object_key)
-        from ks3.connection import Connection
-
         ak = os.getenv("KSYUN_ACCESS_KEY") or os.getenv("KS3_ACCESS_KEY")
         sk = os.getenv("KSYUN_SECRET_KEY") or os.getenv("KS3_SECRET_KEY")
         if not ak or not sk:
             raise ValueError("KS3 credentials are not configured")
-        conn = Connection(ak, sk, host=self._endpoint())
+        connection_class = importlib.import_module("ks3.connection").Connection
+        conn = connection_class(ak, sk, host=self._endpoint())
         key = conn.get_bucket(bucket).get_key(object_key)
         if key is None:
             raise FileNotFoundError(object_key)
-        return key.get_contents_as_string()
+        content = key.get_contents_as_string()
+        if not isinstance(content, bytes):
+            raise TypeError("KS3 object content must be bytes")
+        return content
 
     @staticmethod
     def _ensure_bucket(conn: Any, bucket_name: str):

ksadk/conversations/attachments.py

@@ -1,8 +1,8 @@
 from __future__ import annotations
 
 import base64
+import importlib
 import io
-import json
 import mimetypes
 import zipfile
 from pathlib import Path, PurePosixPath
@@ -168,7 +168,9 @@ def resolve_attachment_storage_path(file_uri: str) -> Optional[Path]:
     return None
 
 
-def read_attachment_bytes(storage_path: Optional[Path], *, size_limit: Optional[int] = None) -> Optional[bytes]:
+def read_attachment_bytes(
+    storage_path: Optional[Path], *, size_limit: Optional[int] = None
+) -> Optional[bytes]:
     if storage_path is None or not storage_path.is_file():
         return None
 
@@ -272,12 +274,7 @@ def build_attachment_prompt_text(result: Mapping[str, Any]) -> str:
 
     size_bytes = result.get("size_bytes")
     if size_bytes is not None:
-        return (
-            "[上传文件: "
-            f"{display_name}, "
-            f"mime={mime_type}, "
-            f"bytes={size_bytes}]"
-        )
+        return "[上传文件: " f"{display_name}, " f"mime={mime_type}, " f"bytes={size_bytes}]"
 
     return f"[上传文件引用: {display_name}, mime={mime_type}]"
 
@@ -353,9 +350,11 @@ def _build_attachment_result_from_raw(
     if raw is None:
         result["status"] = "partial" if size_bytes else "failed"
         result["warnings"] = [
-            "附件原始内容不可用，当前仅保留元数据摘要。"
-            if size_bytes
-            else "附件内容无法读取，请重新上传或检查文件句柄是否仍可访问。"
+            (
+                "附件原始内容不可用，当前仅保留元数据摘要。"
+                if size_bytes
+                else "附件内容无法读取，请重新上传或检查文件句柄是否仍可访问。"
+            )
         ]
         return result
 
@@ -420,7 +419,9 @@ def _extract_document_attachment(result: dict[str, Any], raw: bytes) -> dict[str
         if text:
             return _with_text(result, text=text, extraction_method=extractor[1])
         result["status"] = "failed"
-        result["warnings"] = [f"{suffix.lstrip('.').upper()} 文档抽取失败，请检查文件是否损坏或重新导出后重试。"]
+        result["warnings"] = [
+            f"{suffix.lstrip('.').upper()} 文档抽取失败，请检查文件是否损坏或重新导出后重试。"
+        ]
         result["extraction_method"] = extractor[1]
         return result
 
@@ -435,7 +436,9 @@ def _extract_document_attachment(result: dict[str, Any], raw: bytes) -> dict[str
 
 
 def _extract_image_attachment(result: dict[str, Any], raw: bytes) -> dict[str, Any]:
-    ocr = perform_ocr(raw, str(result.get("mime_type") or ""), str(result.get("display_name") or ""))
+    ocr = perform_ocr(
+        raw, str(result.get("mime_type") or ""), str(result.get("display_name") or "")
+    )
     result["image"] = {"ocr_engine": ocr.get("engine") or ""}
     if ocr.get("text"):
         return _with_text(result, text=ocr["text"], extraction_method="image_ocr")
@@ -524,9 +527,7 @@ def _extract_archive_attachment(result: dict[str, Any], raw: bytes) -> dict[str,
                 }
             )
             if child_result.get("text"):
-                extracted_chunks.append(
-                    f"[{normalized_path}]\n{child_result['text']}"
-                )
+                extracted_chunks.append(f"[{normalized_path}]\n{child_result['text']}")
 
     result["archive"] = {
         "entries": entries,
@@ -578,9 +579,11 @@ def _load_attachment_bytes(attachment: Mapping[str, Any]) -> Optional[bytes]:
             return None
         return raw if len(raw) <= _MAX_PROCESS_BYTES else None
 
-    raw = read_attachment_uri_bytes(attachment.get("file_uri"), size_limit=_MAX_PROCESS_BYTES)
-    if raw is not None:
-        return raw
+    stored_raw = read_attachment_uri_bytes(
+        attachment.get("file_uri"), size_limit=_MAX_PROCESS_BYTES
+    )
+    if stored_raw is not None:
+        return stored_raw
     return None
 
 
@@ -621,7 +624,11 @@ def _extract_xlsx_text(raw: bytes) -> str:
                 shared_strings = []
 
         rows: list[str] = []
-        for name in sorted(item for item in archive.namelist() if item.startswith("xl/worksheets/") and item.endswith(".xml")):
+        for name in sorted(
+            item
+            for item in archive.namelist()
+            if item.startswith("xl/worksheets/") and item.endswith(".xml")
+        ):
             try:
                 root = ET.fromstring(archive.read(name))
             except Exception:
@@ -648,7 +655,9 @@ def _extract_xlsx_text(raw: bytes) -> str:
                             if isinstance(child.tag, str) and child.tag.endswith("}t")
                         )
                     else:
-                        value_text = next((child.text or "" for child in cell if child.tag.endswith("}v")), "")
+                        value_text = next(
+                            (child.text or "" for child in cell if child.tag.endswith("}v")), ""
+                        )
                     if value_text.strip():
                         values.append(value_text.strip())
                 if values:
@@ -679,17 +688,19 @@ def _extract_xml_text_from_zip(raw: bytes, *, prefixes: tuple[str, ...]) -> str:
     texts: list[str] = []
     with archive:
         for name in sorted(
-            item for item in archive.namelist() if item.endswith(".xml") and item.startswith(prefixes)
+            item
+            for item in archive.namelist()
+            if item.endswith(".xml") and item.startswith(prefixes)
         ):
             try:
                 root = ET.fromstring(archive.read(name))
             except Exception:
                 continue
-            fragment = [
-                node.text.strip()
-                for node in root.iter()
-                if isinstance(node.tag, str) and node.tag.endswith("}t") and (node.text or "").strip()
-            ]
+            fragment = []
+            for node in root.iter():
+                text = node.text or ""
+                if isinstance(node.tag, str) and node.tag.endswith("}t") and text.strip():
+                    fragment.append(text.strip())
             if fragment:
                 texts.append("\n".join(fragment))
     return "\n\n".join(texts)
@@ -710,22 +721,18 @@ def _pdf_text_quality_is_poor(text: str) -> bool:
     normalized = "".join(ch for ch in text if not ch.isspace())
     if len(normalized) < 20:
         return True
-    readable = sum(
-        1
-        for ch in normalized
-        if ch.isalnum() or ("\u4e00" <= ch <= "\u9fff")
-    )
+    readable = sum(1 for ch in normalized if ch.isalnum() or ("\u4e00" <= ch <= "\u9fff"))
     return readable / max(len(normalized), 1) < 0.5
 
 
 def _perform_rapidocr(raw: bytes) -> str:
     try:
-        from rapidocr_onnxruntime import RapidOCR
+        rapidocr_module = importlib.import_module("rapidocr_onnxruntime")
     except Exception:
         return ""
 
     try:
-        engine = RapidOCR()
+        engine = rapidocr_module.RapidOCR()
         result, _ = engine(raw)
     except Exception:
         return ""
@@ -741,7 +748,8 @@ def _perform_rapidocr(raw: bytes) -> str:
 def _perform_tesseract_ocr(raw: bytes) -> str:
     try:
         from PIL import Image
-        import pytesseract
+
+        pytesseract = importlib.import_module("pytesseract")
     except Exception:
         return ""
 
@@ -755,7 +763,7 @@ def _perform_tesseract_ocr(raw: bytes) -> str:
             text = pytesseract.image_to_string(image, lang=lang)
         except Exception:
             continue
-        if text and text.strip():
+        if isinstance(text, str) and text.strip():
             return text.strip()
     return ""
 

ksadk/conversations/compaction_pipeline.py

@@ -87,9 +87,7 @@ def _bool_env(name: str, default: bool) -> bool:
 def candidate_tokens(groups: Sequence[Sequence[SessionEvent]]) -> int:
     """估算 candidate groups 的总 token(用于 pipeline 渐进停止判断)。"""
     return sum(
-        estimate_text_tokens(extract_event_text(event))
-        for group in groups
-        for event in group
+        estimate_text_tokens(extract_event_text(event)) for group in groups for event in group
     )
 
 
@@ -108,12 +106,7 @@ def _tool_signature(event: SessionEvent) -> str | None:
         return None
     content = event.content or {}
     metadata = event.metadata or {}
-    name = str(
-        metadata.get("tool_name")
-        or content.get("name")
-        or content.get("tool_name")
-        or ""
-    )
+    name = str(metadata.get("tool_name") or content.get("name") or content.get("tool_name") or "")
     # 参数优先取 metadata.tool_args(真实 runtime),回退 content.arguments(合成/历史)。
     arguments = (
         metadata.get("tool_args")
@@ -264,8 +257,14 @@ def microcompact_cold_groups(
 
     # 尾部 N 组保留(它们可能还被模型需要),更早的组视为冷组。
     cold_rounds = _microcompact_cold_rounds()
-    cold_groups = list(groups[:-cold_rounds]) if cold_rounds < len(groups) else []
-    tail_groups = list(groups[-cold_rounds:]) if cold_rounds < len(groups) else list(groups)
+    cold_groups = (
+        [list(group) for group in groups[:-cold_rounds]] if cold_rounds < len(groups) else []
+    )
+    tail_groups = (
+        [list(group) for group in groups[-cold_rounds:]]
+        if cold_rounds < len(groups)
+        else [list(group) for group in groups]
+    )
 
     if not cold_groups:
         return MicrocompactResult(
@@ -323,7 +322,8 @@ def build_working_set_metadata(
 ) -> dict[str, Any]:
     """L5 working set 恢复(保守版):只记 metadata,不读文件内容。
 
-    recent_files: 调用方从 workspace_state 取最近 N 个文件的 {path, mtime_ns, size_bytes, read_range}。
+    recent_files: 调用方从 workspace_state 取最近 N 个文件的
+        {path, mtime_ns, size_bytes, read_range}。
     active_tools: 调用方从 describe_agentengine_tools 取 enabled 工具名。
     下一轮 prompt 注入时只提示"这些文件最近读过",不注入内容(避免 token 膨胀)。
     """

ksadk/conversations/compaction_prompt.py

@@ -92,10 +92,12 @@ def build_compaction_prompt_messages(
     不把 prompt 字符串散落到 runtime 编排里。
     """
 
-    groups_text = "\n\n".join(
-        _format_group(group, index=index + 1)
-        for index, group in enumerate(groups_to_compact)
-    ).strip() or "无可压缩内容"
+    groups_text = (
+        "\n\n".join(
+            _format_group(group, index=index + 1) for index, group in enumerate(groups_to_compact)
+        ).strip()
+        or "无可压缩内容"
+    )
     user_prompt = _SUMMARY_USER_PROMPT.format(
         model_metadata=json.dumps(dict(model_metadata or {}), ensure_ascii=False, indent=2),
         previous_summary=previous_summary.strip() or "无",
@@ -115,7 +117,9 @@ def extract_summary_text(response_text: str) -> str:
     if not raw:
         return ""
 
-    summary_match = re.search(r"<summary>\s*(.*?)\s*</summary>", raw, flags=re.DOTALL | re.IGNORECASE)
+    summary_match = re.search(
+        r"<summary>\s*(.*?)\s*</summary>", raw, flags=re.DOTALL | re.IGNORECASE
+    )
     if summary_match:
         return summary_match.group(1).strip()
 

ksadk/conversations/context.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import json
 import re
+from collections.abc import Mapping, Sequence
 from typing import Any, Dict, Iterable, List
 
 from ksadk.sessions.base import SessionEvent
@@ -33,9 +34,7 @@ TRANSCRIPT_EVENT_TYPES = {
     "context_checkpoint",
 }
 
-DATA_URL_RE = re.compile(
-    r"data:(?P<mime>[A-Za-z0-9.+-]+/[A-Za-z0-9.+-]+);base64,[A-Za-z0-9+/=_-]+"
-)
+DATA_URL_RE = re.compile(r"data:(?P<mime>[A-Za-z0-9.+-]+/[A-Za-z0-9.+-]+);base64,[A-Za-z0-9+/=_-]+")
 BASE64_FIELD_RE = re.compile(
     r"(?P<prefix>['\"](?P<field>file_data|data|bytes|base64)['\"]\s*:\s*['\"])(?P<value>[A-Za-z0-9+/=_-]{512,})(?P<suffix>['\"])",
     re.IGNORECASE,
@@ -79,7 +78,9 @@ def extract_event_text(event: SessionEvent) -> str:
     if text:
         return sanitize_event_text_for_context(text)
 
-    return sanitize_event_text_for_context(extract_text_from_event_parts(content.get("parts") or []))
+    return sanitize_event_text_for_context(
+        extract_text_from_event_parts(content.get("parts") or [])
+    )
 
 
 def canonical_event_type(
@@ -109,7 +110,11 @@ def canonical_event_type(
         return "run_checkpoint"
     if raw in {"run_resume", "runtime_resume"}:
         return "run_resume"
-    if raw in {"assistant", "model"} or role in {"assistant", "model"} or author in {"assistant", "model"}:
+    if (
+        raw in {"assistant", "model"}
+        or role in {"assistant", "model"}
+        or author in {"assistant", "model"}
+    ):
         return "assistant_message"
     return "user_message"
 
@@ -157,7 +162,9 @@ def build_request_history(messages: Iterable[Dict[str, Any]]) -> List[Dict[str,
 
 def compacted_until_seq_id(events: List[SessionEvent]) -> int:
     """读取最新 checkpoint 覆盖到哪一个 seq_id。"""
-    checkpoints = [event for event in events if canonical_event_type(event.event_type) == "context_checkpoint"]
+    checkpoints = [
+        event for event in events if canonical_event_type(event.event_type) == "context_checkpoint"
+    ]
     if not checkpoints:
         return 0
     latest = checkpoints[-1]
@@ -301,3 +308,211 @@ def build_history_from_events(events: List[SessionEvent]) -> List[Dict[str, str]
         if role in {"user", "model"} and content:
             history.append({"role": role, "content": content})
     return history
+
+
+def _responses_json_string(value: Any, *, default: str = "") -> str:
+    if value is None:
+        return default
+    if isinstance(value, str):
+        return value or default
+    try:
+        return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+    except (TypeError, ValueError):
+        return str(value)
+
+
+def _responses_message(role: str, text: Any) -> dict[str, Any] | None:
+    normalized_text = sanitize_event_text_for_context(text).strip()
+    if not normalized_text:
+        return None
+    return {
+        "role": role,
+        "content": [{"type": "input_text", "text": normalized_text}],
+    }
+
+
+def _event_content_function_part(event: SessionEvent, part_name: str) -> Mapping[str, Any] | None:
+    content = event.content or {}
+    parts = content.get("parts") or []
+    for part in parts:
+        if not isinstance(part, Mapping):
+            continue
+        value = part.get(part_name)
+        if isinstance(value, Mapping):
+            return value
+    return None
+
+
+def _response_tool_call_id(event: SessionEvent) -> str:
+    metadata = event.metadata or {}
+    for key in ("tool_call_id", "call_id", "run_id"):
+        value = metadata.get(key)
+        if value:
+            return str(value)
+    receipt = metadata.get("tool_receipt")
+    if isinstance(receipt, Mapping):
+        for key in ("tool_call_id", "call_id", "run_id"):
+            value = receipt.get(key)
+            if value:
+                return str(value)
+    resume_input = metadata.get("resume_input")
+    if isinstance(resume_input, Mapping):
+        for key in ("tool_call_id", "call_id", "run_id"):
+            value = resume_input.get(key)
+            if value:
+                return str(value)
+    return ""
+
+
+def _response_tool_call_item(event: SessionEvent) -> dict[str, Any] | None:
+    metadata = event.metadata or {}
+    content = event.content or {}
+    function_call = _event_content_function_part(event, "function_call") or {}
+    name = str(
+        metadata.get("tool_name")
+        or content.get("name")
+        or content.get("tool_name")
+        or function_call.get("name")
+        or ""
+    ).strip()
+    arguments: Any = metadata.get("tool_args")
+    if arguments is None:
+        arguments = (
+            content.get("arguments")
+            or content.get("args")
+            or content.get("input")
+            or function_call.get("args")
+            or function_call.get("arguments")
+            or {}
+        )
+    call_id = _response_tool_call_id(event)
+    if not name or not call_id:
+        return None
+    return {
+        "type": "function_call",
+        "call_id": call_id,
+        "name": name,
+        "arguments": _responses_json_string(arguments, default="{}"),
+    }
+
+
+def _response_tool_output_item(event: SessionEvent) -> dict[str, Any] | None:
+    metadata = event.metadata or {}
+    content = event.content or {}
+    function_response = _event_content_function_part(event, "function_response") or {}
+    output: Any = metadata.get("tool_output") if "tool_output" in metadata else None
+    if output is None:
+        resume_input = metadata.get("resume_input")
+        if isinstance(resume_input, Mapping) and "output" in resume_input:
+            output = resume_input.get("output")
+    if output is None:
+        output = (
+            content.get("output")
+            or content.get("result")
+            or function_response.get("response")
+            or extract_event_text(event)
+        )
+    call_id = _response_tool_call_id(event)
+    if not call_id:
+        return None
+    return {
+        "type": "function_call_output",
+        "call_id": call_id,
+        "output": _responses_json_string(output),
+    }
+
+
+def project_responses_history(events: List[SessionEvent]) -> List[dict[str, Any]]:
+    """Project the compacted transcript into OpenAI Responses input items.
+
+    The checkpoint summary represents the compacted prefix. Only the retained
+    tail is replayed as typed tool items, so an old call_id is never fabricated
+    from a text summary. Events without a reliable call id fall back to the
+    existing explanatory message representation instead of emitting an invalid
+    ``function_call_output`` item.
+    """
+    projected: List[dict[str, Any]] = []
+    projected_call_ids: set[str] = set()
+    compacted_until = compacted_until_seq_id(events)
+    checkpoint = next(
+        (
+            event
+            for event in reversed(events)
+            if canonical_event_type(event.event_type) == "context_checkpoint"
+        ),
+        None,
+    )
+    if checkpoint:
+        summary_message = _responses_message("assistant", extract_event_text(checkpoint))
+        if summary_message:
+            projected.append(summary_message)
+
+    for event in events:
+        event_type = canonical_event_type(
+            event.event_type,
+            author=event.author,
+            role=str((event.content or {}).get("role") or ""),
+        )
+        if event.seq_id <= compacted_until and event_type != "context_checkpoint":
+            continue
+        if event_type not in TRANSCRIPT_EVENT_TYPES:
+            continue
+        if event_type in {"context_checkpoint", "compaction_boundary"}:
+            continue
+
+        if event_type == "tool_call":
+            item = _response_tool_call_item(event)
+            if item:
+                projected.append(item)
+                projected_call_ids.add(str(item["call_id"]))
+                continue
+            message = _responses_message("assistant", f"[tool_call] {extract_event_text(event)}")
+        elif event_type == "tool_result":
+            item = _response_tool_output_item(event)
+            if item and str(item["call_id"]) in projected_call_ids:
+                projected.append(item)
+                continue
+            message = _responses_message("user", f"[tool_result] {extract_event_text(event)}")
+        elif event_type == "assistant_message":
+            message = _responses_message("assistant", extract_event_text(event))
+        elif event_type == "approval_request":
+            message = _responses_message(
+                "assistant", f"[approval_request] {extract_event_text(event)}"
+            )
+        elif event_type == "approval_response":
+            message = _responses_message("user", f"[approval_response] {extract_event_text(event)}")
+        elif event_type == "attachment_ref":
+            message = _responses_message("user", f"[attachment] {extract_event_text(event)}")
+        else:
+            message = _responses_message("user", extract_event_text(event))
+        if message:
+            projected.append(message)
+
+    return projected
+
+
+def build_responses_history_from_messages(
+    messages: Sequence[Mapping[str, Any]],
+) -> List[dict[str, Any]]:
+    """Normalize request-provided prior messages for Responses history."""
+    history: List[dict[str, Any]] = []
+    for message in messages or []:
+        role = str(message.get("role") or "").strip().lower()
+        if role == "model":
+            role = "assistant"
+        if role not in {"user", "assistant"}:
+            continue
+
+        content = message.get("input_content")
+        if not isinstance(content, Sequence) or isinstance(content, (str, bytes, bytearray)):
+            content = message.get("content")
+        if isinstance(content, Sequence) and not isinstance(content, (str, bytes, bytearray)):
+            content_items = [dict(item) for item in content if isinstance(item, Mapping)]
+            if content_items:
+                history.append({"role": role, "content": content_items})
+                continue
+
+        item = _responses_message(role, message.get("content"))
+        if item:
+            history.append(item)
+    return history