agentengine-sdk-python 0.8.4__py3-none-any.whl → 0.8.6__py3-none-any.whl

ksadk/context_engine/assembler.py

@@ -13,6 +13,7 @@ from __future__ import annotations
 from dataclasses import dataclass
 from typing import Any, Literal
 
+from ksadk.context_engine.instruction_authority import validate_instruction_authority
 from ksadk.context_engine.models import ContextItem, ContextPlan
 
 ProjectionFormat = Literal["chat", "responses"]
@@ -52,6 +53,9 @@ def _split_prompt_and_rest(selected: list[ContextItem]) -> tuple[str, list[Conte
     prompt_text = ""
     rest: list[ContextItem] = []
     for item in selected:
+        validate_instruction_authority(
+            kind=item.kind, trust_level=item.trust_level, metadata=item.metadata
+        )
         if item.kind == "compiled_prompt":
             prompt_text = (
                 (prompt_text + "\n\n" + _item_text(item)).strip("\n\n")
@@ -74,6 +78,11 @@ def _role_for(item: ContextItem) -> str:
         return "assistant"
     if item.kind == "tool_result":
         return "tool"
+    # 其他 kind（如 ContextSection 的 resource_manifest）可显式声明投影
+    # 角色：trust="system" 的段应进 system 层，而非被当作 assistant 文本。
+    role = item.metadata.get("role")
+    if isinstance(role, str):
+        return role
     return "assistant"
 
 

ksadk/context_engine/capabilities.py

@@ -10,7 +10,7 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from typing import Any, Literal
 
 DeploymentMode = Literal["local", "ksadk_managed_cloud", "external_managed"]
@@ -277,6 +277,48 @@ def capability_hash(caps: ContextCapabilities) -> str:
     return "sha256:" + hashlib.sha256(serialized.encode("utf-8")).hexdigest()
 
 
+def _prepare_state_hook_exported(runner: Any) -> bool:
+    """runner 模块是否导出可调用的 ``ksadk_prepare_state`` hook。
+
+    hook 模式下 runner 不走 ``_to_state`` 注入历史，messages 单一来源是 checkpointer
+    恢复（append-only reducer），ksadk compaction 的输出无法进入最终模型输入。
+    """
+    module = getattr(runner, "_module", None)
+    hook = getattr(module, "ksadk_prepare_state", None)
+    return callable(hook)
+
+
+def _durable_checkpoint_active(runner: Any) -> bool:
+    """runner 图上是否已挂 durable checkpointer（托管重建 ready 或 capability 报告支持）。"""
+    describe = getattr(runner, "describe_checkpoint_capability", None)
+    if callable(describe):
+        try:
+            info = describe()
+        except Exception:
+            info = None
+        if isinstance(info, dict) and info.get("Supported"):
+            return True
+    return getattr(runner, "_managed_checkpoint_state", "") == "ready"
+
+
+def _downgrade_compaction_owner_for_checkpoint_hook(
+    runner: Any, caps: ContextCapabilities
+) -> ContextCapabilities:
+    """durable checkpointer + ``ksadk_prepare_state`` hook 同时存在时，compaction 降级 framework。
+
+    该组合下 checkpointer 独占 messages（framework 侧压缩/摘要直接作用于 checkpointer
+    状态），ksadk compaction 只能写 session event store 的 append-only
+    ``context_checkpoint`` 事件，对模型输入零贡献——继续声明 ``compaction_owner="ksadk"``
+    会让 compaction 门控在每个双阈值触发点白耗一次摘要 LLM 调用。降级后
+    ``_plan_compaction`` 落 ``none`` 带，不产生 LLM 调用。其余字段不变。
+    """
+    if caps.compaction_owner != "ksadk":
+        return caps
+    if not _prepare_state_hook_exported(runner) or not _durable_checkpoint_active(runner):
+        return caps
+    return replace(caps, compaction_owner="framework")
+
+
 def capabilities_for_runner(runner: Any | None) -> ContextCapabilities:
     """统一 lookup：优先 runner 自身的 ``describe_context_capabilities()``，否则按 detection
     type 显式分派，未知走 DEFAULT。
@@ -285,20 +327,26 @@ def capabilities_for_runner(runner: Any | None) -> ContextCapabilities:
     ``describe_context_capabilities``
     走 ``_capabilities_for_detection_type``，故本函数对 BaseRunner 子类不会递归。已被 compaction
     门控（``runtime_preparation`` proactive compaction）与 shadow plan / conformance 测试消费。
+    运行时证据覆盖：durable checkpointer + prepare_state hook 同时存在时，
+    ``compaction_owner`` 从 ``ksadk`` 降级为 ``framework``（见
+    ``_downgrade_compaction_owner_for_checkpoint_hook``）。
     """
     if runner is None:
         return DEFAULT_CONTEXT_CAPABILITIES()
 
+    caps: ContextCapabilities | None = None
     describe = getattr(runner, "describe_context_capabilities", None)
     if callable(describe):
         try:
             caps = describe()
         except Exception:
             caps = None
-        if isinstance(caps, ContextCapabilities):
-            return caps
+        if not isinstance(caps, ContextCapabilities):
+            caps = None
+    if caps is None:
+        caps = _capabilities_for_detection_type(_runner_type_value(runner))
 
-    return _capabilities_for_detection_type(_runner_type_value(runner))
+    return _downgrade_compaction_owner_for_checkpoint_hook(runner, caps)
 
 
 # ---- Capability Mismatch 检测与熔断（方案 §6.1 / §8.3）----

ksadk/context_engine/contributors.py

@@ -14,13 +14,47 @@ from __future__ import annotations
 
 import asyncio
 import logging
+from collections.abc import Awaitable, Callable
+from contextlib import suppress
+from copy import deepcopy
 from dataclasses import dataclass, field
 from typing import Any, Literal, Sequence
 
+from ksadk.context_engine.instruction_authority import validate_instruction_authority
 from ksadk.context_engine.models import ContextItem, ContextTrustLevel
 
 logger = logging.getLogger(__name__)
 
+# Keep an uncooperative producer owned until it settles. Its late value is
+# drained, never admitted into a collection that has already timed out.
+_PENDING_CONTRIBUTOR_TASKS: set[asyncio.Task] = set()
+
+
+def _drain_contributor(task: asyncio.Task) -> None:
+    _PENDING_CONTRIBUTOR_TASKS.discard(task)
+    with suppress(asyncio.CancelledError, Exception):
+        task.exception()
+
+
+async def _read_contribution(
+    callback: Callable[[ContextContributionRequest], Awaitable[list[ContextItem]]],
+    request: ContextContributionRequest,
+    *,
+    deadline: float,
+) -> list[ContextItem]:
+    loop = asyncio.get_running_loop()
+    task = asyncio.create_task(callback(request))
+    _PENDING_CONTRIBUTOR_TASKS.add(task)
+    task.add_done_callback(_drain_contributor)
+    try:
+        done, _ = await asyncio.wait((task,), timeout=max(0, deadline - loop.time()))
+        if not done or loop.time() >= deadline:
+            raise asyncio.TimeoutError
+        return task.result()
+    finally:
+        if not task.done():
+            task.cancel()
+
 ContributorFailureMode = Literal["skip", "warn", "fail"]
 ContributorCacheability = Literal["stable", "turn", "none"]
 
@@ -278,8 +312,10 @@ class ContributionResult:
 
 
 def _admit_contribution_items(
-    contributor: ContextContributor,
     items: object,
+    *,
+    capabilities: ContributorCapabilities,
+    contributor_id: str,
 ) -> tuple[list[ContextItem], str | None]:
     """Validate one Contributor result and enforce its declared token ceiling.
 
@@ -292,8 +328,10 @@ def _admit_contribution_items(
 
     if not isinstance(items, list) or not all(isinstance(item, ContextItem) for item in items):
         raise TypeError("ContextContributor must return a list of ContextItem values")
+    # Admission owns a detached snapshot, including nested content/metadata.
+    # A producer retaining its objects cannot rewrite the granted plan later.
+    items = deepcopy(items)
 
-    capabilities = contributor.capabilities
     if capabilities.max_tokens < 0:
         raise ValueError("ContextContributor max_tokens cannot be negative")
     if capabilities.timeout_ms <= 0:
@@ -314,6 +352,9 @@ def _admit_contribution_items(
             raise ValueError(
                 "ContextContributor cannot elevate item trust above its registered level"
             )
+        validate_instruction_authority(
+            kind=item.kind, trust_level=item.trust_level, metadata=item.metadata
+        )
         if item.estimated_tokens < 0:
             raise ValueError("ContextContributor estimated_tokens cannot be negative")
         if used_tokens + item.estimated_tokens > capabilities.max_tokens:
@@ -325,7 +366,7 @@ def _admit_contribution_items(
     warning = None
     if omitted:
         warning = (
-            f"{contributor.id()}: omitted {omitted} context item(s) that exceeded "
+            f"{contributor_id}: omitted {omitted} context item(s) that exceeded "
             f"the {capabilities.max_tokens}-token contributor budget"
         )
     return admitted, warning
@@ -345,32 +386,54 @@ async def run_contributors(
     - 返回的 ContextItem 总 token 受各自 ``max_tokens`` 约束（Planner 再做全局预算）。
     """
 
-    async def _run_one(c: ContextContributor) -> tuple[str, list[ContextItem], str, str | None]:
-        timeout = max(c.capabilities.timeout_ms, 1) / 1000.0
+    # Freeze every registration before dispatching any producer. Reading its
+    # mutable owner again after await would let it replace the original grant.
+    request_snapshot = deepcopy(request)
+    registered = tuple(
+        (c.contribute, c.capabilities, c.id(), deepcopy(request_snapshot)) for c in contributors
+    )
+
+    async def _run_one(
+        callback: Callable[[ContextContributionRequest], Awaitable[list[ContextItem]]],
+        capabilities: ContributorCapabilities,
+        contributor_id: str,
+        scoped_request: ContextContributionRequest,
+    ) -> tuple[str, list[ContextItem], str, str | None]:
+        timeout = max(capabilities.timeout_ms, 1) / 1000.0
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + timeout
         try:
-            raw_items = await asyncio.wait_for(c.contribute(request), timeout=timeout)
-            items, budget_warning = _admit_contribution_items(c, raw_items)
+            raw_items = await _read_contribution(callback, scoped_request, deadline=deadline)
+            items, budget_warning = _admit_contribution_items(
+                raw_items, capabilities=capabilities, contributor_id=contributor_id
+            )
+            if loop.time() >= deadline:
+                raise asyncio.TimeoutError
         except asyncio.TimeoutError:
-            return c.id(), [], "timeout", f"{c.id()}: timeout"
+            return contributor_id, [], "timeout", f"{contributor_id}: timeout"
         except Exception as exc:  # noqa: BLE001
-            if c.capabilities.failure_mode == "fail":
+            if capabilities.failure_mode == "fail":
                 raise
-            warning = f"{c.id()}: {exc}" if c.capabilities.failure_mode == "warn" else None
-            return c.id(), [], "error", warning
-        return c.id(), items, "ok", budget_warning
+            warning = (
+                f"{contributor_id}: contributor_failed ({type(exc).__name__})"
+                if capabilities.failure_mode == "warn" else None
+            )
+            return contributor_id, [], "error", warning
+        return contributor_id, items, "ok", budget_warning
 
-    results = await asyncio.gather(*[_run_one(c) for c in contributors], return_exceptions=True)
+    results = await asyncio.gather(*[_run_one(*binding) for binding in registered],
+                                   return_exceptions=True)
     all_items: list[ContextItem] = []
     status: dict[str, str] = {}
     warnings: list[str] = []
-    for contributor, r in zip(contributors, results):
+    for (_, capabilities, contributor_id, _), r in zip(registered, results):
         if isinstance(r, BaseException):
             if isinstance(r, asyncio.CancelledError):
                 raise r
-            if contributor.capabilities.failure_mode == "fail":
+            if capabilities.failure_mode == "fail":
                 raise r
-            warnings.append(f"{contributor.id()}: {r}")
-            status[contributor.id()] = "error"
+            warnings.append(f"{contributor_id}: contributor_failed ({type(r).__name__})")
+            status[contributor_id] = "error"
             continue
         cid, items, st, warn = r
         status[cid] = st

ksadk/context_engine/instruction_authority.py

@@ -0,0 +1,18 @@
+"""Keep the privileged input layer bound to host-granted instruction trust."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+
+def validate_instruction_authority(
+    *, kind: str, trust_level: str, metadata: Mapping[str, object]
+) -> None:
+    # Names and projection hints are not grants. Recalled/attached data must
+    # not enter the compiled prefix or system/developer layer by relabeling it.
+    role = metadata.get("role")
+    privileged = kind == "compiled_prompt" or (
+        isinstance(role, str) and role in {"system", "developer"}
+    )
+    if privileged and trust_level not in {"platform", "developer"}:
+        raise ValueError("context item lacks instruction authority")

ksadk/conversations/attachment_storage.py

@@ -103,8 +103,11 @@ def _region() -> str:
 
 
 class AttachmentStorageService:
-    def __init__(self, *, root_dir: Path | None = None):
+    def __init__(self, *, root_dir: Path | None = None, owner_scope_ref: str | None = None):
         self.root_dir = root_dir or uploads_dir()
+        self.owner_scope_ref = str(owner_scope_ref or "").strip()
+        if root_dir is None and self.owner_scope_ref:
+            self.root_dir = self.root_dir / "identities" / self.owner_scope_ref
 
     async def store(
         self,
@@ -149,6 +152,7 @@ class AttachmentStorageService:
             "mime_type": resolved_mime,
             "size_bytes": len(data),
             "fallback_reason": "",
+            "owner_scope_ref": self.owner_scope_ref,
         }
         try:
             self._run_async_sync(
@@ -363,11 +367,14 @@ class AttachmentStorageService:
         local_path.write_bytes(data)
         return local_path
 
-    @staticmethod
-    def _object_key(*, file_id: str, display_name: str) -> str:
+    def _object_key(self, *, file_id: str, display_name: str) -> str:
         suffix = Path(display_name).suffix
         stored_name = file_id if suffix and file_id.endswith(suffix) else f"{file_id}{suffix}"
         day = datetime.utcnow().strftime("%Y/%m/%d")
+        if self.owner_scope_ref:
+            return (
+                f"agents/_runtime/identities/{self.owner_scope_ref}/attachments/{day}/{stored_name}"
+            )
         return f"agents/_runtime/attachments/{day}/{stored_name}"
 
     @staticmethod

ksadk/conversations/attachments.py

@@ -94,7 +94,9 @@ def looks_like_textual_attachment(mime_type: str, display_name: str) -> bool:
     return is_textual_mime(mime_type) or suffix in _TEXT_FILE_EXTENSIONS
 
 
-def extract_pdf_text(raw: bytes) -> str:
+def extract_pdf_text(
+    raw: bytes, *, max_pages: int | None = 10, extraction_metadata: dict | None = None,
+) -> str:
     try:
         from pypdf import PdfReader
     except Exception:
@@ -106,13 +108,28 @@ def extract_pdf_text(raw: bytes) -> str:
         return ""
 
     segments: List[str] = []
-    for page in reader.pages[:10]:
+    total, failed, empty, text_bytes = len(reader.pages), 0, 0, 0
+    pages = reader.pages if max_pages is None else reader.pages[:max_pages]
+    for page in pages:
         try:
             page_text = page.extract_text() or ""
         except Exception:
             page_text = ""
+            failed += 1
         if page_text:
+            text_bytes += len(page_text.encode("utf-8")) + 1
+            if text_bytes > _MAX_PROCESS_BYTES:
+                raise ValueError("document_extraction_text_limit")
             segments.append(page_text)
+        else:
+            empty += 1
+
+    if extraction_metadata is not None:
+        extraction_metadata.update(
+            total_pages=total, extracted_pages=len(pages), failed_page_count=failed,
+            pages_without_text=empty,
+            text_extraction_complete=len(pages) == total and not failed and not empty,
+        )
 
     return "\n".join(segments).strip()
 
@@ -133,7 +150,9 @@ def _path_within_root(path: Path, root: Path) -> bool:
     return resolved == resolved_root or resolved_root in resolved.parents
 
 
-def resolve_attachment_storage_path(file_uri: str) -> Optional[Path]:
+def resolve_attachment_storage_path(
+    file_uri: str, *, owner_scope_ref: str | None = None
+) -> Optional[Path]:
     normalized_uri = (file_uri or "").strip()
     if not normalized_uri:
         return None
@@ -146,11 +165,17 @@ def resolve_attachment_storage_path(file_uri: str) -> Optional[Path]:
         if not file_id:
             return None
 
-        restored = AttachmentStorageService().ensure_local_path(normalized_uri)
+        restored = AttachmentStorageService(owner_scope_ref=owner_scope_ref).ensure_local_path(
+            normalized_uri
+        )
         if restored is not None and restored.is_file():
             return restored.resolve()
 
-        uploads_dir = resolve_uploads_dir().resolve()
+        uploads_dir = resolve_uploads_dir()
+        normalized_owner = str(owner_scope_ref or "").strip()
+        if normalized_owner:
+            uploads_dir = uploads_dir / "identities" / normalized_owner
+        uploads_dir = uploads_dir.resolve()
         safe_file_id = Path(file_id).name
         if not safe_file_id:
             return None
@@ -186,8 +211,11 @@ def read_attachment_uri_bytes(
     file_uri: Any,
     *,
     size_limit: Optional[int] = None,
+    owner_scope_ref: str | None = None,
 ) -> Optional[bytes]:
-    storage_path = resolve_attachment_storage_path(str(file_uri or ""))
+    storage_path = resolve_attachment_storage_path(
+        str(file_uri or ""), owner_scope_ref=owner_scope_ref
+    )
     if storage_path is None:
         return None
     return read_attachment_bytes(storage_path, size_limit=size_limit)
@@ -223,7 +251,9 @@ def build_attachment_results(attachments: List[Dict[str, Any]]) -> list[dict[str
     return [build_attachment_result(attachment) for attachment in attachments or []]
 
 
-def build_attachment_result(attachment: Mapping[str, Any]) -> dict[str, Any]:
+def build_attachment_result(
+    attachment: Mapping[str, Any], *, capture_full_text: bool = False,
+) -> dict[str, Any]:
     display_name = str(attachment.get("display_name") or "uploaded_file")
     mime_type = str(attachment.get("mime_type") or "application/octet-stream")
     transport = str(attachment.get("transport") or "")
@@ -241,6 +271,7 @@ def build_attachment_result(attachment: Mapping[str, Any]) -> dict[str, Any]:
         size_bytes=size_bytes,
         raw=raw,
         allow_archive=True,
+        capture_full_text=capture_full_text,
     )
 
 
@@ -274,7 +305,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}, mime={mime_type}, bytes={size_bytes}]"
 
     return f"[上传文件引用: {display_name}, mime={mime_type}]"
 
@@ -333,6 +364,7 @@ def _build_attachment_result_from_raw(
     size_bytes: Any,
     raw: bytes | None,
     allow_archive: bool,
+    capture_full_text: bool = False,
 ) -> dict[str, Any]:
     result: dict[str, Any] = {
         "display_name": display_name,
@@ -359,9 +391,9 @@ def _build_attachment_result_from_raw(
         return result
 
     if result["kind"] == "text":
-        return _extract_text_attachment(result, raw)
+        return _extract_text_attachment(result, raw, capture_full_text=capture_full_text)
     if result["kind"] == "document":
-        return _extract_document_attachment(result, raw)
+        return _extract_document_attachment(result, raw, capture_full_text=capture_full_text)
     if result["kind"] == "image":
         return _extract_image_attachment(result, raw)
     if result["kind"] == "archive" and allow_archive:
@@ -372,7 +404,9 @@ def _build_attachment_result_from_raw(
     return result
 
 
-def _extract_text_attachment(result: dict[str, Any], raw: bytes) -> dict[str, Any]:
+def _extract_text_attachment(
+    result: dict[str, Any], raw: bytes, *, capture_full_text: bool = False,
+) -> dict[str, Any]:
     text = _decode_text_bytes(raw)
     if not text:
         result["status"] = "failed"
@@ -380,24 +414,31 @@ def _extract_text_attachment(result: dict[str, Any], raw: bytes) -> dict[str, An
         result["extraction_method"] = "text_decode"
         return result
 
-    return _with_text(result, text=text, extraction_method="text_decode")
+    return _with_text(result, text=text, extraction_method="text_decode",
+                      capture_full_text=capture_full_text)
 
 
-def _extract_document_attachment(result: dict[str, Any], raw: bytes) -> dict[str, Any]:
+def _extract_document_attachment(
+    result: dict[str, Any], raw: bytes, *, capture_full_text: bool = False,
+) -> dict[str, Any]:
     suffix = Path(str(result.get("display_name") or "")).suffix.lower()
     mime_type = str(result.get("mime_type") or "")
 
     if suffix == ".pdf" or mime_type == "application/pdf":
-        native_text = extract_pdf_text(raw)
+        metadata = {}
+        native_text = (extract_pdf_text(raw, max_pages=None, extraction_metadata=metadata)
+                       if capture_full_text else extract_pdf_text(raw))
         if native_text and not _pdf_text_quality_is_poor(native_text):
-            result["document"] = {"format": "pdf"}
-            return _with_text(result, text=native_text, extraction_method="pdf_native")
+            result["document"] = {"format": "pdf", **metadata}
+            return _with_text(result, text=native_text, extraction_method="pdf_native",
+                              capture_full_text=capture_full_text)
 
         ocr = perform_ocr(raw, mime_type, str(result.get("display_name") or ""))
         if ocr.get("text"):
             result["document"] = {"format": "pdf", "ocr_engine": ocr.get("engine") or ""}
             result["warnings"] = ["PDF 原生文本抽取为空或质量较差，已回退到 OCR。"]
-            return _with_text(result, text=ocr["text"], extraction_method="pdf_ocr")
+            return _with_text(result, text=ocr["text"], extraction_method="pdf_ocr",
+                              capture_full_text=capture_full_text)
 
         result["status"] = "failed"
         result["document"] = {"format": "pdf"}
@@ -417,7 +458,8 @@ def _extract_document_attachment(result: dict[str, Any], raw: bytes) -> dict[str
         text = extractor[0](raw)
         result["document"] = dict(extractor[2])
         if text:
-            return _with_text(result, text=text, extraction_method=extractor[1])
+            return _with_text(result, text=text, extraction_method=extractor[1],
+                              capture_full_text=capture_full_text)
         result["status"] = "failed"
         result["warnings"] = [
             f"{suffix.lstrip('.').upper()} 文档抽取失败，请检查文件是否损坏或重新导出后重试。"
@@ -427,7 +469,7 @@ def _extract_document_attachment(result: dict[str, Any], raw: bytes) -> dict[str
 
     if suffix in _TEXT_FILE_EXTENSIONS:
         result["document"] = {"format": suffix.lstrip(".")}
-        return _extract_text_attachment(result, raw)
+        return _extract_text_attachment(result, raw, capture_full_text=capture_full_text)
 
     result["status"] = "partial"
     result["document"] = {"format": suffix.lstrip(".") or "document"}
@@ -559,14 +601,21 @@ def _with_text(
     text: str,
     extraction_method: str,
     status: str = "ok",
+    capture_full_text: bool = False,
 ) -> dict[str, Any]:
     normalized = _normalize_text(text)
     if not normalized:
         return result
+    if capture_full_text and len(normalized.encode("utf-8")) > _MAX_PROCESS_BYTES:
+        raise ValueError("document_extraction_text_limit")
     result["status"] = status
     result["extraction_method"] = extraction_method
+    result["original_text_chars"] = len(normalized)
+    result["text_truncated"] = len(normalized) > _MAX_INLINE_TEXT_CHARS
     result["text"] = _truncate_text(normalized, _MAX_INLINE_TEXT_CHARS)
     result["text_excerpt"] = _truncate_text(normalized, _MAX_TEXT_EXCERPT_CHARS)
+    if capture_full_text and result["text_truncated"]:
+        result["full_text"] = normalized
     return result
 
 
@@ -719,7 +768,7 @@ def _truncate_text(text: str, limit: int) -> str:
 
 def _pdf_text_quality_is_poor(text: str) -> bool:
     normalized = "".join(ch for ch in text if not ch.isspace())
-    if len(normalized) < 20:
+    if not normalized:
         return True
     readable = sum(1 for ch in normalized if ch.isalnum() or ("\u4e00" <= ch <= "\u9fff"))
     return readable / max(len(normalized), 1) < 0.5

ksadk/conversations/contracts.py

@@ -30,6 +30,7 @@ _CAPABILITY = re.compile(r"^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$")
 APPROVAL_MODE_EXTENSION = "ksadk.approval"
 COLLABORATION_MODE_EXTENSION = "ksadk.collaboration"
 GOAL_OBJECTIVE_EXTENSION = "ksadk.goal"
+PRESENTATION_EXTENSION = "ksadk.presentation"
 
 
 class ConversationCapability(ConversationContractModel):
@@ -65,9 +66,7 @@ class ConversationSurface(ConversationContractModel):
         for capabilities, direction in ((self.inputs, "input"), (self.outputs, "output")):
             names = [capability.name for capability in capabilities]
             if len(names) != len(set(names)):
-                raise ValueError(
-                    f"conversation surface must not repeat an {direction} capability"
-                )
+                raise ValueError(f"conversation surface must not repeat an {direction} capability")
         return self
 
     def permits_input(self, field: str) -> bool:
@@ -116,6 +115,15 @@ class ConversationInput(ConversationContractModel):
     def validate_extensions(cls, value: dict[str, Any]) -> dict[str, Any]:
         if any(not _CAPABILITY.fullmatch(key) or "." not in key for key in value):
             raise ValueError("extensions must use namespaced capability keys")
+        if PRESENTATION_EXTENSION in value:
+            presentation = value[PRESENTATION_EXTENSION]
+            if (
+                not isinstance(presentation, dict)
+                or set(presentation) != {"profile"}
+                or not isinstance(presentation["profile"], str)
+                or presentation["profile"] not in {"flat-v1", "agent-block-v1"}
+            ):
+                raise ValueError("ksadk.presentation requires a supported profile only")
         approval = value.get(APPROVAL_MODE_EXTENSION)
         if approval is not None and approval not in {"ask", "risk", "full"}:
             raise ValueError("ksadk.approval must be ask, risk, or full")
@@ -123,9 +131,7 @@ class ConversationInput(ConversationContractModel):
         if collaboration is not None and collaboration not in {"default", "plan"}:
             raise ValueError("ksadk.collaboration must be default or plan")
         goal = value.get(GOAL_OBJECTIVE_EXTENSION)
-        if goal is not None and (
-            not isinstance(goal, str) or not goal.strip() or len(goal) > 4096
-        ):
+        if goal is not None and (not isinstance(goal, str) or not goal.strip() or len(goal) > 4096):
             raise ValueError("ksadk.goal must be a non-empty string up to 4096 characters")
         return value
 
@@ -168,9 +174,7 @@ class ConversationInput(ConversationContractModel):
             required.append("goal")
         extension_capabilities = {
             APPROVAL_MODE_EXTENSION: "approval",
-            COLLABORATION_MODE_EXTENSION: "plan"
-            if self.collaboration_mode == "plan"
-            else None,
+            COLLABORATION_MODE_EXTENSION: "plan" if self.collaboration_mode == "plan" else None,
             GOAL_OBJECTIVE_EXTENSION: "goal",
         }
         required.extend(
@@ -194,11 +198,13 @@ class ConversationItem(ConversationContractModel):
         "assistant_text",
         "reasoning",
         "tool_call",
+        "tool_result",
         "approval",
         "progress",
         "plan",
         "goal",
         "artifact",
+        "agent",
         "a2ui",
         "error",
         "unknown",
@@ -222,6 +228,19 @@ class ConversationItem(ConversationContractModel):
     def validate_lifecycle(self) -> "ConversationItem":
         if self.operation == "completed" and self.lifecycle not in {"completed", "failed"}:
             raise ValueError("completed operation requires a terminal lifecycle")
+        if self.kind == "agent":
+            from ksadk.a2a.presentation import ExecutionScopeDescriptor
+
+            descriptor = ExecutionScopeDescriptor.model_validate(self.payload)
+            if self.payload_schema_ref != "conversation.item.agent/v1":
+                raise ValueError("agent item requires conversation.item.agent/v1")
+            if self.capability_ref != "agent.block" or not self.parent_item_id:
+                raise ValueError("agent item requires agent.block and a triggering parent item")
+            if self.native_ref.get("scopeId") != descriptor.scope_id:
+                raise ValueError("agent item scope does not match descriptor")
+            terminal = descriptor.status in {"completed", "failed", "cancelled"}
+            if terminal != (self.lifecycle in {"completed", "failed"}):
+                raise ValueError("agent item lifecycle does not match descriptor")
         return self