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

ksadk/events/adapters/_a2a_support.py

@@ -0,0 +1,275 @@
+"""A2A adapter 的错误/上下文/状态 dataclass 与校验辅助（纯移动自 adapters.a2a，行为不变）。"""
+
+from __future__ import annotations
+
+import hashlib
+import math
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any, Literal, Protocol, cast
+
+from a2a.types import (
+    GetTaskRequest,
+    Task,
+    TaskState,
+    TaskStatus,
+)
+from google.protobuf.json_format import MessageToDict
+from pydantic import JsonValue
+
+from ksadk.events.canonical import (
+    OutputRef,
+    RuntimeEvent,
+    SourceRef,
+)
+from ksadk.events.content import (
+    ContentSnapshot,
+    ContentValue,
+)
+from ksadk.events.identity import (
+    stable_scope_id,
+)
+
+ReconciliationReason = Literal["terminal", "reconnect", "subscription_rebuild"]
+
+_ACTIVE_STATES = frozenset({TaskState.TASK_STATE_SUBMITTED, TaskState.TASK_STATE_WORKING})
+_INTERACTION_STATES = frozenset(
+    {TaskState.TASK_STATE_INPUT_REQUIRED, TaskState.TASK_STATE_AUTH_REQUIRED}
+)
+_TERMINAL_STATES = frozenset(
+    {
+        TaskState.TASK_STATE_COMPLETED,
+        TaskState.TASK_STATE_FAILED,
+        TaskState.TASK_STATE_CANCELED,
+        TaskState.TASK_STATE_REJECTED,
+    }
+)
+
+
+class A2AMappingError(ValueError):
+    """An A2A protobuf violates the native identity or content contract."""
+
+    def __init__(self, code: str, field_name: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+        self.field_name = field_name
+        self.source = "a2a"
+
+
+def _fail(code: str, field_name: str, message: str) -> None:
+    raise A2AMappingError(code, field_name, message)
+
+
+@dataclass
+class A2AAdapterContext:
+    """Runtime invocation facts and non-durable pre-store sequence placeholders."""
+
+    run_id: str
+    context_id: str
+    task_id: str | None
+    initial_seq: int = 0
+    _next_seq: int = field(init=False, repr=False)
+    _direct_message_id: str | None = field(default=None, init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        self.run_id = _required_string(self.run_id, "runtime run_id")
+        self.context_id = _required_string(self.context_id, "context_id")
+        if self.task_id is not None:
+            self.task_id = _required_string(self.task_id, "task_id")
+        if self.initial_seq < 0:
+            raise ValueError("A2A initial_seq must be non-negative")
+        self._next_seq = self.initial_seq
+
+    @property
+    def scope_id(self) -> str:
+        if self.task_id is not None:
+            return stable_scope_id("a2a", self.context_id, self.task_id)
+        if self._direct_message_id is not None:
+            return stable_scope_id("a2a", self.context_id, "message", self._direct_message_id)
+        _fail(
+            "missing_native_identity",
+            "task_id/message_id",
+            "A2A scope requires a task_id or direct message_id",
+        )
+
+    @property
+    def native_run_id(self) -> str:
+        return _required_string(self.task_id or self._direct_message_id, "task_id/message_id")
+
+    def bind_direct_message(self, message_id: str) -> None:
+        native_message_id = _required_string(message_id, "message.message_id")
+        if self.task_id is not None:
+            return
+        if self._direct_message_id not in {None, native_message_id}:
+            _fail(
+                "direct_message_scope_collision",
+                "message.message_id",
+                "A2A direct response changed message scope",
+            )
+        self._direct_message_id = native_message_id
+
+    def allocate_placeholder_seq(self) -> int:
+        value = self._next_seq
+        self._next_seq += 1
+        return value
+
+    def peek_placeholder_seq(self) -> int:
+        """Return the next placeholder without consuming it."""
+
+        return self._next_seq
+
+
+@dataclass(frozen=True)
+class A2AReconciliationResult:
+    """Result of GetTask reconciliation.
+
+    ``consistent`` means the emitted projection matches the fetched Task.
+    ``terminal`` independently reports whether that Task was terminal.
+    """
+
+    events: tuple[RuntimeEvent, ...]
+    consistent: bool
+    terminal: bool
+    attempt_id: str
+    error: str | None = None
+
+
+class _A2AClient(Protocol):
+    async def get_task(self, request: GetTaskRequest, **kwargs: Any) -> Task: ...
+
+
+@dataclass
+class _ArtifactState:
+    artifact_id: str
+    item_id: str
+    parts: dict[str, ContentValue] = field(default_factory=dict)
+    part_order: list[str] = field(default_factory=list)
+    closed: bool = False
+    present: bool = True
+
+    def snapshot(self) -> ContentSnapshot:
+        return ContentSnapshot(parts=tuple(self.parts[part_id] for part_id in self.part_order))
+
+
+@dataclass(frozen=True)
+class _MessageState:
+    signature: bytes
+
+
+@dataclass(frozen=True)
+class _Occurrence:
+    native_event_id: str | None
+    native_cursor: str | None
+    identity: str
+    provisional: bool
+    duplicate: bool = False
+
+
+@dataclass
+class _SnapshotScope:
+    """Shared plumbing for one GetTask snapshot projection pass."""
+
+    task: Task
+    context: A2AAdapterContext
+    source: SourceRef
+    timestamp: float
+    occurrence: _Occurrence
+    terminal: bool
+    reason: ReconciliationReason
+    attempt_id: str
+    events: list[RuntimeEvent] = field(default_factory=list)
+    _output_refs: list[OutputRef] = field(default_factory=list)
+    _output_ref_keys: set[tuple[str, str]] = field(default_factory=set)
+
+    def add_output_ref(self, item_id: str) -> None:
+        key = (self.context.scope_id, item_id)
+        if key not in self._output_ref_keys:
+            self._output_ref_keys.add(key)
+            self._output_refs.append(OutputRef(scope_id=self.context.scope_id, item_id=item_id))
+
+
+def _proto_fingerprint(value: object) -> str:
+    serialize = getattr(value, "SerializeToString", None)
+    if not callable(serialize):
+        _fail(
+            "invalid_protobuf_payload",
+            "event",
+            "A2A occurrence payload must be a protobuf message",
+        )
+    payload = cast(bytes, serialize(deterministic=True))
+    return hashlib.sha256(payload).hexdigest()
+
+
+def _validate_unique_parts(parts: tuple[ContentValue, ...], field_name: str) -> None:
+    seen: set[str] = set()
+    for part in parts:
+        if part.part_id in seen:
+            _fail(
+                "duplicate_part_id",
+                field_name,
+                f"A2A snapshot contains duplicate part_id {part.part_id!r}",
+            )
+        seen.add(part.part_id)
+
+
+def _metadata(struct: Any) -> dict[str, JsonValue]:
+    if struct is None:
+        return {}
+    return cast(
+        dict[str, JsonValue],
+        MessageToDict(struct, preserving_proto_field_name=True),
+    )
+
+
+def _optional_metadata_string(
+    metadata: Mapping[str, JsonValue],
+    *keys: str,
+) -> str | None:
+    for key in keys:
+        value = metadata.get(key)
+        if value is not None:
+            text = str(value).strip()
+            if text:
+                return text
+    return None
+
+
+def _required_metadata_string(metadata: Mapping[str, JsonValue], key: str) -> str:
+    value = _optional_metadata_string(metadata, key)
+    if value is None:
+        _fail(
+            "missing_part_metadata",
+            f"part.metadata.{key}",
+            f"A2A typed part requires metadata {key!r}",
+        )
+    return value
+
+
+def _required_string(value: object, field_name: str) -> str:
+    text = str(value or "").strip()
+    if not text:
+        _fail(
+            "missing_native_identity",
+            field_name,
+            f"A2A {field_name} must be non-empty",
+        )
+    return text
+
+
+def _status_message_id(status: TaskStatus) -> str | None:
+    if status.HasField("message") and status.message.message_id:
+        return status.message.message_id
+    return None
+
+
+def _parts_text(parts: Any) -> str:
+    return "".join(str(part.text) for part in parts if part.text)
+
+
+def _timestamp(value: float) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        _fail("invalid_timestamp", "timestamp", "timestamp must be finite")
+    result = float(value)
+    if not math.isfinite(result):
+        _fail("invalid_timestamp", "timestamp", "timestamp must be finite")
+    return result

ksadk/events/adapters/_codex_interactions.py

@@ -0,0 +1,375 @@
+"""CodexEventAdapter 的交互(interaction/serverRequest)映射方法（纯移动自 codex，行为不变）。
+
+以 mixin 形式被 :class:`CodexEventAdapter` 继承。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, Callable, Literal
+
+from pydantic import JsonValue
+
+from ksadk.events.adapters._codex_items import (
+    _APPROVAL_KINDS,
+    _CONTROL_REQUEST_BUILDERS,
+    CodexAdapterContext,
+    _approval_response,
+    _elicitation_request,
+    _envelope,
+    _InteractionState,
+    _protocol_source,
+    _structured_response_data,
+    _thread_continuation_identity,
+)
+from ksadk.events.adapters._codex_validators import (
+    _fail,
+    _json_value,
+    _mapping,
+    _question_schema,
+    _request_id,
+    _required_string,
+    _required_text,
+)
+from ksadk.events.canonical import (
+    ApprovalRequest,
+    ApprovalResponse,
+    InteractionRequest,
+    InteractionRequested,
+    InteractionResolved,
+    InteractionResponse,
+    RunInterrupted,
+    RunProgress,
+    RuntimeEvent,
+    SourceRef,
+    StructuredInputRequest,
+    StructuredInputResponse,
+)
+from ksadk.events.identity import stable_item_id, stable_scope_id
+
+
+class _CodexInteractionMixin:
+    def _map_control_interaction_request(
+        self,
+        *,
+        message: Mapping[str, Any],
+        method: str,
+        params: Mapping[str, Any],
+        context: CodexAdapterContext,
+        cursor: str,
+        timestamp: float,
+    ) -> tuple[RuntimeEvent, ...]:
+        """Map process-level v2 requests without inventing a turn interruption."""
+
+        request_id = _request_id(message.get("id"), "id")
+        if request_id in self._interactions:
+            _fail(
+                "interaction_already_pending",
+                "id",
+                f"Codex JSON-RPC request {request_id!r} is already pending",
+            )
+        thread_id = f"runtime:{context.run_id}"
+        turn_id = "control"
+        scope_id = stable_scope_id("codex", thread_id, turn_id)
+        interaction_id = stable_item_id("codex", scope_id, "interaction", method, request_id)
+        request = _CONTROL_REQUEST_BUILDERS[method](params)
+        state = _InteractionState(
+            request_id=request_id,
+            interaction_id=interaction_id,
+            interaction_kind="structured_input",
+            scope_id=scope_id,
+            thread_id=thread_id,
+            turn_id=turn_id,
+            native_item_id=request_id,
+            method=method,
+            interrupts_run=False,
+        )
+        self._interactions[request_id] = state
+        source = _protocol_source(
+            method=method,
+            cursor=cursor,
+            thread_id=thread_id,
+            turn_id=turn_id,
+            native_item_id=request_id,
+            native_event_id=request_id,
+        )
+        return (
+            InteractionRequested(
+                **_envelope(context, cursor, timestamp)(
+                    scope_id, interaction_id, "interaction.requested", "structured_input", source
+                ),
+                interaction_id=interaction_id,
+                interaction_kind="structured_input",
+                request=request,
+            ),
+        )
+
+    def _map_server_request_resolved(
+        self,
+        *,
+        params: Mapping[str, Any],
+        context: CodexAdapterContext,
+        cursor: str,
+        timestamp: float,
+    ) -> tuple[RuntimeEvent, ...]:
+        """Close a request that Codex resolved outside its JSON-RPC response path."""
+
+        thread_id = _required_string(params.get("threadId"), "params.threadId")
+        request_id = _request_id(params.get("requestId"), "params.requestId")
+        state = self._interactions.get(request_id)
+        if state is None:
+            return self._map_known_notification(
+                method="serverRequest/resolved",
+                params=params,
+                context=context,
+                cursor=cursor,
+                timestamp=timestamp,
+            )
+        if state.thread_id != thread_id:
+            _fail(
+                "interaction_scope_mismatch",
+                "params.threadId",
+                "Codex serverRequest/resolved threadId does not match the pending request",
+            )
+        resolved = self._resolve_interaction(
+            state,
+            cursor=cursor,
+            timestamp=timestamp,
+            context=context,
+            source=_protocol_source(
+                method="serverRequest/resolved",
+                cursor=cursor,
+                thread_id=state.thread_id,
+                turn_id=state.turn_id,
+                native_item_id=state.native_item_id,
+                native_event_id=request_id,
+            ),
+            response=(
+                ApprovalResponse(
+                    decision="canceled",
+                    data={"source": "serverRequest/resolved", "requestId": request_id},
+                )
+                if state.interaction_kind == "approval"
+                else StructuredInputResponse(
+                    data={"source": "serverRequest/resolved", "requestId": request_id}
+                )
+            ),
+        )
+        return (resolved,)
+
+    def _map_interaction_request(
+        self,
+        *,
+        message: Mapping[str, Any],
+        method: str,
+        params: Mapping[str, Any],
+        env: Callable[..., dict[str, Any]],
+        context: CodexAdapterContext,
+        cursor: str,
+        timestamp: float,
+        thread_id: str,
+        turn_id: str,
+        scope_id: str,
+        interrupts_run: bool,
+    ) -> tuple[RuntimeEvent, ...]:
+        request_id = _request_id(message.get("id"), "id")
+        if request_id in self._interactions:
+            _fail(
+                "interaction_already_pending",
+                "id",
+                f"Codex JSON-RPC request {request_id!r} is already pending",
+            )
+        if method == "item/tool/call":
+            native_item_id = _required_string(params.get("callId"), "params.callId")
+        elif method == "mcpServer/elicitation/request":
+            native_item_id = request_id
+        else:
+            native_item_id = _required_string(params.get("itemId"), "params.itemId")
+        native_interaction_id = params.get("approvalId") or request_id
+        native_interaction_id = _required_string(native_interaction_id, "params.approvalId")
+        interaction_id = stable_item_id(
+            "codex", scope_id, "interaction", method, native_interaction_id
+        )
+        kind: Literal["approval", "structured_input"]
+        request: InteractionRequest
+        question_ids: frozenset[str] = frozenset()
+        secret_question_ids: frozenset[str] = frozenset()
+        if method == "item/tool/requestUserInput":
+            kind = "structured_input"
+            prompt, schema, question_ids, secret_question_ids = _question_schema(
+                params.get("questions")
+            )
+            request = StructuredInputRequest(prompt=prompt, schema=schema)
+        elif method == "mcpServer/elicitation/request":
+            kind = "structured_input"
+            request = _elicitation_request(params)
+        else:
+            kind = "approval"
+            request = ApprovalRequest(
+                call_id=native_item_id,
+                kind=_APPROVAL_KINDS[method],
+                detail=_json_value(params),
+            )
+        state = _InteractionState(
+            request_id=request_id,
+            interaction_id=interaction_id,
+            interaction_kind=kind,
+            scope_id=scope_id,
+            thread_id=thread_id,
+            turn_id=turn_id,
+            native_item_id=native_item_id,
+            method=method,
+            interrupts_run=interrupts_run,
+            question_ids=question_ids,
+            secret_question_ids=secret_question_ids,
+        )
+        self._interactions[request_id] = state
+        source = _protocol_source(
+            method=method,
+            cursor=cursor,
+            thread_id=thread_id,
+            turn_id=turn_id,
+            native_item_id=native_item_id,
+            native_event_id=request_id,
+        )
+        requested = InteractionRequested(
+            **env(scope_id, interaction_id, "interaction.requested", kind, source),
+            interaction_id=interaction_id,
+            interaction_kind=kind,
+            request=request,
+        )
+        if not interrupts_run:
+            return (requested,)
+        return (
+            requested,
+            RunInterrupted(
+                **env(scope_id, turn_id, "run.interrupted", interaction_id, source),
+                status="interrupted",
+                reason="Codex requires user interaction",
+                interaction_id=interaction_id,
+                continuation_id=self._thread_continuations.setdefault(
+                    thread_id, _thread_continuation_identity(thread_id)[1]
+                ),
+            ),
+        )
+
+    def _map_jsonrpc_response(
+        self,
+        message: Mapping[str, Any],
+        context: CodexAdapterContext,
+        cursor: str,
+        timestamp: float,
+    ) -> tuple[RuntimeEvent, ...]:
+        request_id = _request_id(message.get("id"), "id")
+        if request_id in self._resume_requests:
+            if "error" in message:
+                thread_id = self._resume_requests.pop(request_id)
+                self._pending_resume_by_thread.pop(thread_id, None)
+                _fail(
+                    "thread_resume_failed",
+                    "error",
+                    "Codex thread/resume failed with a JSON-RPC error",
+                )
+            _mapping(message.get("result"), "result")
+            return ()
+        state = self._interactions.get(request_id)
+        if state is None:
+            _fail(
+                "unknown_jsonrpc_response",
+                "id",
+                f"Codex response has no pending request: {request_id}",
+            )
+        is_error_response = "error" in message
+        result: Mapping[str, Any] = {}
+        response: InteractionResponse
+        if is_error_response:
+            error = _mapping(message.get("error"), "error")
+            code = error.get("code")
+            if isinstance(code, bool) or not isinstance(code, int):
+                _fail(
+                    "invalid_interaction_response",
+                    "error.code",
+                    "Codex JSON-RPC error.code must be an integer",
+                )
+            _required_text(error.get("message"), "error.message")
+            sanitized_error: dict[str, JsonValue] = {
+                "code": code,
+                "messagePresent": True,
+                "dataPresent": "data" in error,
+            }
+            if state.interaction_kind == "approval":
+                response = ApprovalResponse(
+                    decision="canceled", data={"jsonrpcError": sanitized_error}
+                )
+            else:
+                response = StructuredInputResponse(data={"jsonrpcError": sanitized_error})
+        else:
+            result = _mapping(message.get("result"), "result")
+            if state.interaction_kind == "approval":
+                response = _approval_response(state.method, result)
+            else:
+                response = StructuredInputResponse(data=_structured_response_data(state, result))
+        source = _protocol_source(
+            method="jsonrpc/response",
+            cursor=cursor,
+            thread_id=state.thread_id,
+            turn_id=state.turn_id,
+            native_item_id=state.native_item_id,
+            native_event_id=request_id,
+        )
+        resolved = self._resolve_interaction(
+            state,
+            cursor=cursor,
+            timestamp=timestamp,
+            context=context,
+            source=source,
+            response=response,
+        )
+        if is_error_response:
+            return (resolved,)
+        resumes = (
+            isinstance(response, ApprovalResponse) and response.decision in {"approved", "rejected"}
+        ) or (
+            isinstance(response, StructuredInputResponse)
+            and (
+                state.method == "item/tool/requestUserInput"
+                or result.get("action") in {"accept", "decline"}
+            )
+        )
+        if not resumes or not state.interrupts_run:
+            return (resolved,)
+        return (
+            resolved,
+            RunProgress(
+                **_envelope(context, cursor, timestamp)(
+                    state.scope_id, state.turn_id, "run.progress", state.interaction_id, source
+                ),
+                status="running",
+                message="Codex user interaction resolved; turn resumed",
+            ),
+        )
+
+    def _resolve_interaction(
+        self,
+        state: _InteractionState,
+        *,
+        cursor: str,
+        timestamp: float,
+        context: CodexAdapterContext,
+        source: SourceRef,
+        response: InteractionResponse,
+    ) -> InteractionResolved:
+        resolved = InteractionResolved(
+            **_envelope(context, cursor, timestamp)(
+                state.scope_id,
+                state.interaction_id,
+                "interaction.resolved",
+                state.interaction_kind,
+                source,
+            ),
+            interaction_id=state.interaction_id,
+            interaction_kind=state.interaction_kind,
+            response=response,
+        )
+        del self._interactions[state.request_id]
+        return resolved