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

ksadk/configs/settings.py

@@ -628,3 +628,12 @@ def setup_environment(agent_path: Path | str):
         setup_proxy_redirect_if_enabled()
     except Exception:  # noqa: BLE001  代理可选,失败不影响主流程(默认关时本就不触发)
         pass
+
+    # 5. 沙箱控制面 URL 内网探测:在 Pod 内探测 198 公共服务网内网地址,
+    # 可达则覆盖 E2B_API_URL 为内网域名,private_only 节点也能访问沙箱控制面。
+    try:
+        from ksadk.sandbox import setup_sandbox_api_url_if_needed
+
+        setup_sandbox_api_url_if_needed()
+    except Exception:  # noqa: BLE001  沙箱可选,失败不影响主流程
+        pass

ksadk/context_engine/contributors.py

@@ -24,6 +24,14 @@ logger = logging.getLogger(__name__)
 ContributorFailureMode = Literal["skip", "warn", "fail"]
 ContributorCacheability = Literal["stable", "turn", "none"]
 
+_TRUST_RANK: dict[ContextTrustLevel, int] = {
+    "untrusted": 0,
+    "user": 1,
+    "resource": 2,
+    "developer": 3,
+    "platform": 4,
+}
+
 
 @dataclass(frozen=True)
 class ContributorCapabilities:
@@ -131,13 +139,15 @@ class WorkspaceRulesContributor(ContextContributor):
             return []
         items: list[ContextItem] = []
         for index, section in enumerate(sections):
+            raw_tokens = section.metadata.get("tokens", 0)
+            tokens = int(raw_tokens) if isinstance(raw_tokens, (int, str)) else 0
             items.append(
                 _make_item(
                     contributor_id=self.capabilities.contributor_id,
                     trust_level=self.capabilities.trust_level,
                     kind="resource_manifest",
                     content=section.content,
-                    tokens=int(section.metadata.get("tokens", 0)) or 1,
+                    tokens=tokens or 1,
                     source=section.source,
                     metadata={"path": section.metadata.get("path"), "kind": "rule_file"},
                 )
@@ -267,6 +277,60 @@ class ContributionResult:
     warnings: tuple[str, ...]
 
 
+def _admit_contribution_items(
+    contributor: ContextContributor,
+    items: object,
+) -> tuple[list[ContextItem], str | None]:
+    """Validate one Contributor result and enforce its declared token ceiling.
+
+    A Contributor is an untrusted capability boundary.  It cannot promote an
+    item above the trust level granted at registration, mark context as
+    required, return duplicate identities, or make the Host confuse token
+    counts with list indexes.  Items that do not fit the declared budget are
+    deterministically omitted while later, smaller items may still fit.
+    """
+
+    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")
+
+    capabilities = contributor.capabilities
+    if capabilities.max_tokens < 0:
+        raise ValueError("ContextContributor max_tokens cannot be negative")
+    if capabilities.timeout_ms <= 0:
+        raise ValueError("ContextContributor timeout_ms must be positive")
+
+    admitted: list[ContextItem] = []
+    seen_ids: set[str] = set()
+    used_tokens = 0
+    omitted = 0
+    maximum_trust = _TRUST_RANK[capabilities.trust_level]
+    for item in items:
+        if not item.item_id or item.item_id in seen_ids:
+            raise ValueError("ContextContributor item ids must be non-empty and unique")
+        seen_ids.add(item.item_id)
+        if item.required:
+            raise ValueError("ContextContributor cannot mark context as required")
+        if _TRUST_RANK[item.trust_level] > maximum_trust:
+            raise ValueError(
+                "ContextContributor cannot elevate item trust above its registered level"
+            )
+        if item.estimated_tokens < 0:
+            raise ValueError("ContextContributor estimated_tokens cannot be negative")
+        if used_tokens + item.estimated_tokens > capabilities.max_tokens:
+            omitted += 1
+            continue
+        admitted.append(item)
+        used_tokens += item.estimated_tokens
+
+    warning = None
+    if omitted:
+        warning = (
+            f"{contributor.id()}: omitted {omitted} context item(s) that exceeded "
+            f"the {capabilities.max_tokens}-token contributor budget"
+        )
+    return admitted, warning
+
+
 async def run_contributors(
     contributors: Sequence[ContextContributor],
     request: ContextContributionRequest,
@@ -284,24 +348,25 @@ async def run_contributors(
     async def _run_one(c: ContextContributor) -> tuple[str, list[ContextItem], str, str | None]:
         timeout = max(c.capabilities.timeout_ms, 1) / 1000.0
         try:
-            items = await asyncio.wait_for(c.contribute(request), timeout=timeout)
+            raw_items = await asyncio.wait_for(c.contribute(request), timeout=timeout)
+            items, budget_warning = _admit_contribution_items(c, raw_items)
         except asyncio.TimeoutError:
             return c.id(), [], "timeout", f"{c.id()}: timeout"
         except Exception as exc:  # noqa: BLE001
             if c.capabilities.failure_mode == "fail":
                 raise
-            return c.id(), [], "error", f"{c.id()}: {exc}"
-        # 单 Contributor 总 token 约束
-        if items and sum(i.estimated_tokens for i in items) > c.capabilities.max_tokens:
-            items = items[: c.capabilities.max_tokens]  # best-effort 限条数
-        return c.id(), items, "ok", None
+            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
 
     results = await asyncio.gather(*[_run_one(c) for c in contributors], return_exceptions=True)
     all_items: list[ContextItem] = []
     status: dict[str, str] = {}
     warnings: list[str] = []
     for contributor, r in zip(contributors, results):
-        if isinstance(r, Exception):
+        if isinstance(r, BaseException):
+            if isinstance(r, asyncio.CancelledError):
+                raise r
             if contributor.capabilities.failure_mode == "fail":
                 raise r
             warnings.append(f"{contributor.id()}: {r}")

ksadk/conversations/__init__.py

@@ -11,6 +11,25 @@ def _exports(module: str, *names: str) -> dict[str, tuple[str, str]]:
 
 
 _EXPORTS = {
+    **_exports(
+        "ksadk.conversations.contracts",
+        "ConversationCapability",
+        "ConversationInput",
+        "ConversationAttachmentPart",
+        "ConversationItem",
+        "ConversationSurface",
+        "ConversationTextPart",
+        "validate_conversation_input",
+        "validate_surface_input",
+    ),
+    **_exports(
+        "ksadk.conversations.projector",
+        "project_conversation_item",
+    ),
+    **_exports(
+        "ksadk.conversations.reducer",
+        "ConversationItemReducer",
+    ),
     **_exports(
         "ksadk.conversations.attachments",
         "decode_inline_data",

ksadk/conversations/context.py

@@ -5,6 +5,8 @@ import re
 from collections.abc import Mapping, Sequence
 from typing import Any, Dict, Iterable, List
 
+from ksadk.events.canonical import ItemCompleted, parse_runtime_event
+from ksadk.events.content import TextContent
 from ksadk.sessions.base import SessionEvent
 from ksadk.tools.result_budget import (
     ToolResultBudget,
@@ -99,6 +101,60 @@ def extract_event_text(event: SessionEvent) -> str:
     )
 
 
+def _canonical_completed_message(
+    event: SessionEvent,
+) -> tuple[str, str, tuple[str, str]] | None:
+    """Return one canonical assistant message without flattening its identity.
+
+    Canonical RuntimeEvents are persisted inside the existing ``SessionEvent``
+    carrier.  Legacy transcript projection only inspects carrier-level fields,
+    so an ``item.completed`` message otherwise disappears from the next turn's
+    history.  The canonical event id and ``(scope_id, item_id)`` are both kept:
+    replays are idempotent, while equal text from different items remains
+    distinct.
+    """
+
+    raw = (event.content or {}).get("runtime_event")
+    if not isinstance(raw, Mapping):
+        return None
+    try:
+        canonical = parse_runtime_event(dict(raw))
+    except (TypeError, ValueError):
+        return None
+    if (
+        not isinstance(canonical, ItemCompleted)
+        or canonical.item_kind != "message"
+        or event.event_type != canonical.event_type
+    ):
+        return None
+    text = sanitize_event_text_for_context(
+        "".join(
+            part.text for part in canonical.snapshot.parts if isinstance(part, TextContent)
+        )
+    )
+    if not text:
+        return None
+    return canonical.event_id, text, (canonical.scope_id, canonical.item_id)
+
+
+def _transcript_event_projection(
+    event: SessionEvent,
+) -> tuple[str, str, tuple[str, tuple[str, str]] | None]:
+    canonical_message = _canonical_completed_message(event)
+    if canonical_message is not None:
+        event_id, text, item_identity = canonical_message
+        return "assistant_message", text, (event_id, item_identity)
+    return (
+        canonical_event_type(
+            event.event_type,
+            author=event.author,
+            role=str((event.content or {}).get("role") or ""),
+        ),
+        extract_event_text(event),
+        None,
+    )
+
+
 def canonical_event_type(
     event_type: str | None,
     *,
@@ -276,6 +332,8 @@ def summarize_event_groups(
     因此跨消息提取修正，并在预算上限内保留最新长指令首尾（方案 §9.4）。
     """
     lines: List[str] = []
+    seen_canonical_event_ids: set[str] = set()
+    seen_canonical_items: set[tuple[str, str]] = set()
     if previous_summary:
         lines.append(previous_summary)
     lines.append("Earlier conversation summary:")
@@ -284,14 +342,18 @@ def summarize_event_groups(
     for group in groups:
         snippets: List[str] = []
         for event in group:
-            event_type = canonical_event_type(
-                event.event_type,
-                author=event.author,
-                role=str((event.content or {}).get("role") or ""),
-            )
+            event_type, text, canonical_identity = _transcript_event_projection(event)
+            if canonical_identity is not None:
+                event_id, item_identity = canonical_identity
+                if (
+                    event_id in seen_canonical_event_ids
+                    or item_identity in seen_canonical_items
+                ):
+                    continue
+                seen_canonical_event_ids.add(event_id)
+                seen_canonical_items.add(item_identity)
             if event_type not in TRANSCRIPT_EVENT_TYPES or event_type == "context_checkpoint":
                 continue
-            text = extract_event_text(event)
             if not text:
                 continue
             if event_type in {"assistant_message", "tool_call"}:
@@ -343,6 +405,9 @@ def project_model_messages(
     """
     projected: List[Dict[str, str]] = []
     placeholder_flags: list[bool] = []
+    identity_boundary_flags: list[bool] = []
+    seen_canonical_event_ids: set[str] = set()
+    seen_canonical_items: set[tuple[str, str]] = set()
     compacted_until = compacted_until_seq_id(events)
     checkpoint = next(
         (
@@ -362,21 +427,26 @@ def project_model_messages(
                 }
             )
             placeholder_flags.append(False)
+            identity_boundary_flags.append(False)
 
     for event in events:
-        event_type = canonical_event_type(
-            event.event_type,
-            author=event.author,
-            role=str((event.content or {}).get("role") or ""),
-        )
+        event_type, text, canonical_identity = _transcript_event_projection(event)
         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 canonical_identity is not None:
+            event_id, item_identity = canonical_identity
+            if (
+                event_id in seen_canonical_event_ids
+                or item_identity in seen_canonical_items
+            ):
+                continue
+            seen_canonical_event_ids.add(event_id)
+            seen_canonical_items.add(item_identity)
 
-        text = extract_event_text(event)
         if not text:
             continue
 
@@ -405,12 +475,15 @@ def project_model_messages(
             projected
             and projected[-1]["role"] == role
             and not placeholder_flags[-1]
+            and not identity_boundary_flags[-1]
             and not is_placeholder
+            and canonical_identity is None
         ):
             projected[-1]["content"] = f"{projected[-1]['content']}\n{text}".strip()
         else:
             projected.append({"role": role, "content": text})
             placeholder_flags.append(is_placeholder)
+            identity_boundary_flags.append(canonical_identity is not None)
 
     return projected
 
@@ -553,6 +626,8 @@ def project_responses_history(events: List[SessionEvent]) -> List[dict[str, Any]
     """
     projected: List[dict[str, Any]] = []
     projected_call_ids: set[str] = set()
+    seen_canonical_event_ids: set[str] = set()
+    seen_canonical_items: set[tuple[str, str]] = set()
     compacted_until = compacted_until_seq_id(events)
     checkpoint = next(
         (
@@ -568,17 +643,22 @@ def project_responses_history(events: List[SessionEvent]) -> List[dict[str, Any]
             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 ""),
-        )
+        event_type, text, canonical_identity = _transcript_event_projection(event)
         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 canonical_identity is not None:
+            event_id, item_identity = canonical_identity
+            if (
+                event_id in seen_canonical_event_ids
+                or item_identity in seen_canonical_items
+            ):
+                continue
+            seen_canonical_event_ids.add(event_id)
+            seen_canonical_items.add(item_identity)
 
         if event_type == "tool_call":
             item = _response_tool_call_item(event)
@@ -586,25 +666,25 @@ def project_responses_history(events: List[SessionEvent]) -> List[dict[str, Any]
                 projected.append(item)
                 projected_call_ids.add(str(item["call_id"]))
                 continue
-            message = _responses_message("assistant", f"[tool_call] {extract_event_text(event)}")
+            message = _responses_message("assistant", f"[tool_call] {text}")
         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)}")
+            message = _responses_message("user", f"[tool_result] {text}")
         elif event_type == "assistant_message":
-            message = _responses_message("assistant", extract_event_text(event))
+            message = _responses_message("assistant", text)
         elif event_type == "approval_request":
             message = _responses_message(
-                "assistant", f"[approval_request] {extract_event_text(event)}"
+                "assistant", f"[approval_request] {text}"
             )
         elif event_type == "approval_response":
-            message = _responses_message("user", f"[approval_response] {extract_event_text(event)}")
+            message = _responses_message("user", f"[approval_response] {text}")
         elif event_type == "attachment_ref":
-            message = _responses_message("user", f"[attachment] {extract_event_text(event)}")
+            message = _responses_message("user", f"[attachment] {text}")
         else:
-            message = _responses_message("user", extract_event_text(event))
+            message = _responses_message("user", text)
         if message:
             projected.append(message)
 

ksadk/conversations/contracts.py

@@ -0,0 +1,266 @@
+"""Additive, provider-neutral conversation presentation contracts (v1)."""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+
+def _to_camel(value: str) -> str:
+    head, *tail = value.split("_")
+    return head + "".join(part.capitalize() for part in tail)
+
+
+class ConversationContractModel(BaseModel):
+    model_config = ConfigDict(
+        alias_generator=_to_camel,
+        populate_by_name=True,
+        extra="forbid",
+        frozen=True,
+    )
+
+
+_CAPABILITY = re.compile(r"^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$")
+
+# Provider-neutral wire extensions.  These keys are deliberately namespaced:
+# the stable ConversationInput/v1 envelope must not grow a top-level field for
+# every control exposed by Codex, DSH, or a future AgentProvider.
+APPROVAL_MODE_EXTENSION = "ksadk.approval"
+COLLABORATION_MODE_EXTENSION = "ksadk.collaboration"
+GOAL_OBJECTIVE_EXTENSION = "ksadk.goal"
+
+
+class ConversationCapability(ConversationContractModel):
+    name: str = Field(min_length=1, max_length=128)
+    mode: Literal["native", "translated", "degraded", "unavailable"]
+    reason: str | None = Field(default=None, max_length=512)
+
+    @field_validator("name")
+    @classmethod
+    def validate_name(cls, value: str) -> str:
+        if not _CAPABILITY.fullmatch(value):
+            raise ValueError("capability name must be a namespaced identifier")
+        return value
+
+    @model_validator(mode="after")
+    def validate_reason(self) -> "ConversationCapability":
+        if self.mode in {"degraded", "unavailable"} and not self.reason:
+            raise ValueError("degraded or unavailable capability requires a reason")
+        return self
+
+
+class ConversationSurface(ConversationContractModel):
+    api_version: Literal["conversation.ksadk.io/v1"] = "conversation.ksadk.io/v1"
+    kind: Literal["ConversationSurface"] = "ConversationSurface"
+    surface_id: str = Field(min_length=1, max_length=256)
+    session_id: str = Field(min_length=1, max_length=256)
+    provider_ref: str = Field(min_length=1, max_length=256)
+    inputs: tuple[ConversationCapability, ...] = ()
+    outputs: tuple[ConversationCapability, ...] = ()
+
+    @model_validator(mode="after")
+    def validate_unique_capabilities(self) -> "ConversationSurface":
+        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"
+                )
+        return self
+
+    def permits_input(self, field: str) -> bool:
+        return any(
+            capability.name == field and capability.mode in {"native", "translated"}
+            for capability in self.inputs
+        )
+
+
+class ConversationTextPart(ConversationContractModel):
+    kind: Literal["text"] = "text"
+    text: str = Field(min_length=1, max_length=131072)
+
+
+class ConversationAttachmentPart(ConversationContractModel):
+    kind: Literal["attachment"] = "attachment"
+    attachment_ref: str = Field(min_length=1, max_length=2048)
+    media_type: str = Field(min_length=1, max_length=256)
+    name: str | None = Field(default=None, max_length=1024)
+
+
+ConversationInputPart = ConversationTextPart | ConversationAttachmentPart
+
+
+class ConversationInput(ConversationContractModel):
+    """A provider-neutral foreground turn submitted by a conversation client.
+
+    It deliberately carries only user intent.  A Server/Runtime adapter maps
+    that intent to a provider-specific request after checking the active
+    ConversationSurface; browser clients never forward arbitrary provider
+    parameters.
+    """
+
+    api_version: Literal["conversation.ksadk.io/v1"] = "conversation.ksadk.io/v1"
+    kind: Literal["ConversationInput"] = "ConversationInput"
+    input_id: str = Field(min_length=1, max_length=256)
+    session_id: str = Field(min_length=1, max_length=256)
+    idempotency_key: str = Field(min_length=1, max_length=512)
+    parts: tuple[ConversationInputPart, ...] = Field(min_length=1)
+    model_ref: str | None = Field(default=None, min_length=1, max_length=256)
+    reasoning: str | None = Field(default=None, min_length=1, max_length=64)
+    extensions: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("extensions")
+    @classmethod
+    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")
+        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")
+        collaboration = value.get(COLLABORATION_MODE_EXTENSION)
+        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
+        ):
+            raise ValueError("ksadk.goal must be a non-empty string up to 4096 characters")
+        return value
+
+    @property
+    def approval_mode(self) -> Literal["ask", "risk", "full"] | None:
+        value = self.extensions.get(APPROVAL_MODE_EXTENSION)
+        return value if value in {"ask", "risk", "full"} else None
+
+    @property
+    def collaboration_mode(self) -> Literal["default", "plan"] | None:
+        value = self.extensions.get(COLLABORATION_MODE_EXTENSION)
+        return value if value in {"default", "plan"} else None
+
+    @property
+    def goal_objective(self) -> str | None:
+        value = self.extensions.get(GOAL_OBJECTIVE_EXTENSION)
+        return value if isinstance(value, str) and value else None
+
+    def required_capabilities(self) -> tuple[str, ...]:
+        required: list[str] = []
+        if any(isinstance(part, ConversationTextPart) for part in self.parts):
+            required.append("text")
+        for part in self.parts:
+            if not isinstance(part, ConversationAttachmentPart):
+                continue
+            required.append(
+                "attachment.image"
+                if part.media_type.lower().startswith("image/")
+                else "attachment.file"
+            )
+        if self.model_ref:
+            required.append("model.select")
+        if self.reasoning:
+            required.append("reasoning.effort")
+        if self.approval_mode:
+            required.append("approval")
+        if self.collaboration_mode == "plan":
+            required.append("plan")
+        if self.goal_objective:
+            required.append("goal")
+        extension_capabilities = {
+            APPROVAL_MODE_EXTENSION: "approval",
+            COLLABORATION_MODE_EXTENSION: "plan"
+            if self.collaboration_mode == "plan"
+            else None,
+            GOAL_OBJECTIVE_EXTENSION: "goal",
+        }
+        required.extend(
+            extension_capabilities.get(key, key)
+            for key in self.extensions
+            if extension_capabilities.get(key, key) is not None
+        )
+        return tuple(dict.fromkeys(required))
+
+
+class ConversationItem(ConversationContractModel):
+    api_version: Literal["conversation.ksadk.io/v1"] = "conversation.ksadk.io/v1"
+    kind_version: Literal[1] = 1
+    item_id: str = Field(min_length=1, max_length=512)
+    parent_item_id: str | None = Field(default=None, min_length=1, max_length=512)
+    source_event_ids: tuple[str, ...] = Field(min_length=1)
+    session_id: str = Field(min_length=1, max_length=256)
+    run_id: str = Field(min_length=1, max_length=256)
+    kind: Literal[
+        "user_message",
+        "assistant_text",
+        "reasoning",
+        "tool_call",
+        "approval",
+        "progress",
+        "plan",
+        "goal",
+        "artifact",
+        "a2ui",
+        "error",
+        "unknown",
+    ]
+    operation: Literal["append", "replace", "completed"]
+    lifecycle: Literal["pending", "streaming", "completed", "failed"]
+    visibility: Literal["public", "internal", "hidden"] = "public"
+    payload_schema_ref: str = Field(min_length=1, max_length=256)
+    payload: dict[str, Any] = Field(default_factory=dict)
+    capability_ref: str | None = Field(default=None, max_length=256)
+    native_ref: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("source_event_ids")
+    @classmethod
+    def validate_source_event_ids(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        if any(not item for item in value) or len(value) != len(set(value)):
+            raise ValueError("sourceEventIds must be non-empty and unique")
+        return value
+
+    @model_validator(mode="after")
+    def validate_lifecycle(self) -> "ConversationItem":
+        if self.operation == "completed" and self.lifecycle not in {"completed", "failed"}:
+            raise ValueError("completed operation requires a terminal lifecycle")
+        return self
+
+
+def validate_surface_input(surface: ConversationSurface, payload: dict[str, Any]) -> None:
+    """Reject UI input fields not declared by the active ConversationSurface."""
+
+    extensions = payload.get("extensions", {})
+    if extensions is not None and not isinstance(extensions, dict):
+        raise ValueError("extensions must be an object")
+    for field in payload:
+        if field == "extensions":
+            continue
+        if not surface.permits_input(field):
+            raise ValueError(f"conversation input is not declared by surface: {field}")
+
+
+def validate_conversation_input(
+    surface: ConversationSurface,
+    conversation_input: ConversationInput,
+) -> None:
+    """Apply the same capability allowlist before and after the network hop."""
+
+    if surface.session_id != conversation_input.session_id:
+        raise ValueError("conversation input session does not match active surface")
+    for capability in conversation_input.required_capabilities():
+        if not surface.permits_input(capability):
+            raise ValueError(f"conversation input is not declared by surface: {capability}")
+
+
+__all__ = [
+    "APPROVAL_MODE_EXTENSION",
+    "COLLABORATION_MODE_EXTENSION",
+    "ConversationCapability",
+    "ConversationInput",
+    "ConversationAttachmentPart",
+    "ConversationItem",
+    "ConversationSurface",
+    "ConversationTextPart",
+    "GOAL_OBJECTIVE_EXTENSION",
+    "validate_conversation_input",
+    "validate_surface_input",
+]