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

ksadk/a2a/server.py

@@ -14,7 +14,6 @@ from typing import Any, cast
 
 from a2a.server.agent_execution import RequestContext, SimpleRequestContextBuilder
 from a2a.server.context import ServerCallContext
-from a2a.server.request_handlers import DefaultRequestHandler
 from a2a.server.routes import (
     create_agent_card_routes,
     create_jsonrpc_routes,
@@ -25,8 +24,10 @@ from a2a.types import AgentCard, SendMessageRequest, Task
 
 from ksadk.a2a.card import JSONRPC_PATH, REST_PATH_PREFIX
 from ksadk.a2a.executor import A2ARuntimeExecutor
+from ksadk.a2a.protocol_errors import ProtocolRequestHandler, correct_cancel_rest_route
 from ksadk.a2a.task_adapter import A2ARuntimeTaskAdapter
 from ksadk.a2a.task_store import A2AOwnerContextBuilder
+from ksadk.a2a.tool_activity import PublicToolActivityPolicy
 
 
 class _DurableRequestContextBuilder(SimpleRequestContextBuilder):
@@ -76,6 +77,7 @@ class A2AProtocolServer:
         task_adapter: A2ARuntimeTaskAdapter,
         context_builder: A2AOwnerContextBuilder | None = None,
         include_reasoning: bool = False,
+        public_tool_policy: PublicToolActivityPolicy | None = None,
     ) -> None:
         self.agent_card = agent_card
         self.task_store = task_store
@@ -84,14 +86,18 @@ class A2AProtocolServer:
         self.executor = A2ARuntimeExecutor(
             task_adapter=task_adapter,
             include_reasoning=include_reasoning,
+            public_tool_policy=public_tool_policy,
         )
-        self.request_handler = DefaultRequestHandler(
+        self.request_handler = ProtocolRequestHandler(
             agent_executor=self.executor,
             task_store=task_store,
             agent_card=agent_card,
             request_context_builder=_DurableRequestContextBuilder(task_store),
         )
 
+        self.request_handler.terminal_task_reconciler = getattr(
+            task_adapter, "reconcile_terminal_task", None)
+
     def agent_card_routes(self) -> list[Any]:
         return cast(list[Any], create_agent_card_routes(self.agent_card))
 
@@ -108,11 +114,14 @@ class A2AProtocolServer:
     def rest_routes(self) -> list[Any]:
         return cast(
             list[Any],
-            create_rest_routes(
-                self.request_handler,
-                path_prefix=REST_PATH_PREFIX,
-                context_builder=self.context_builder,
-            ),
+            [
+                correct_cancel_rest_route(route)
+                for route in create_rest_routes(
+                    self.request_handler,
+                    path_prefix=REST_PATH_PREFIX,
+                    context_builder=self.context_builder,
+                )
+            ],
         )
 
 

ksadk/a2a/space_client.py

@@ -2,10 +2,12 @@
 
 from __future__ import annotations
 
+import asyncio
 import hashlib
 import json
 import logging
 import os
+import time
 import uuid
 from collections.abc import AsyncIterator
 from contextlib import AsyncExitStack, asynccontextmanager
@@ -34,6 +36,7 @@ from ksadk.a2a._space_client_events import _SpaceClientEventMixin
 from ksadk.a2a.control_plane import (
     A2AAgentCardClient,
     A2AControlPlane,
+    A2AControlPlaneError,
     A2ARouteInterface,
     CredentialInjection,
     DiscoveredAgent,
@@ -61,6 +64,7 @@ ERR_PUBLIC_EGRESS_DISABLED = "A2A_PUBLIC_EGRESS_DISABLED"
 MAX_A2A_MESSAGE_BYTES = 1024 * 1024
 MAX_A2A_MESSAGE_PARTS = 64
 MAX_A2A_MESSAGE_ID_LENGTH = 128
+INITIAL_SEND_BIND_WAIT_SECONDS = 120.0
 
 
 def _require_opaque_space_id(value: str, *, field_name: str) -> str:
@@ -190,6 +194,14 @@ class A2ASpaceClient(_SpaceClientEventMixin):
                     f"{ENV_A2A_SPACE_IDS} contains multiple Space IDs; pass space_id explicitly"
                 )
             selected_space_id = normalized_space_ids[0]
+        if backend is None and os.getenv("KSADK_A2A_CONTROL_PLANE_URL", "").strip():
+            from ksadk.a2a.control_plane import InternalA2AControlPlaneClient
+            from ksadk.a2a.platform import _managed_http_verify
+
+            backend = InternalA2AControlPlaneClient(
+                os.environ["KSADK_A2A_CONTROL_PLANE_URL"].strip(),
+                httpx_client=httpx_client, verify=_managed_http_verify(),
+            )
         if backend is None:
             from ksadk.a2a.service_env import (
                 resolve_a2a_service_token,
@@ -284,6 +296,46 @@ class A2ASpaceClient(_SpaceClientEventMixin):
         self._check_egress(agent)
         return agent
 
+    @property
+    def control_plane(self) -> A2AControlPlane:
+        return self._backend
+
+    @asynccontextmanager
+    async def open_prepared_message_stream(self, prepared: PreparedA2AOperation, message: Message):
+        """Guarded wire port; the invocation service owns mapping and persistence."""
+        self._validate_prepared_ids(prepared)
+        agent = self._agent_from_prepared(prepared)
+        async with self._operation_client(agent, prepared) as (client, context):
+            yield client.send_message(SendMessageRequest(message=message), context=context)
+
+    async def get_prepared_task(self, prepared: PreparedA2AOperation):
+        self._validate_prepared_ids(prepared)
+        remote = self._require_remote_task(prepared)
+        async with self._operation_client(self._agent_from_prepared(prepared), prepared) as (
+            client,
+            context,
+        ):
+            task = await client.get_task(GetTaskRequest(id=remote.remote_task_id), context=context)
+            self._validate_remote_task_observation(
+                remote.remote_task_id, remote.remote_context_id, task
+            )
+            return task
+
+    async def cancel_prepared_task(self, prepared: PreparedA2AOperation):
+        self._validate_prepared_ids(prepared)
+        remote = self._require_remote_task(prepared)
+        async with self._operation_client(self._agent_from_prepared(prepared), prepared) as (
+            client,
+            context,
+        ):
+            task = await client.cancel_task(
+                CancelTaskRequest(id=remote.remote_task_id), context=context
+            )
+            self._validate_remote_task_observation(
+                remote.remote_task_id, remote.remote_context_id, task
+            )
+            return task
+
     async def send_message(
         self,
         agent_id: str,
@@ -294,15 +346,31 @@ class A2ASpaceClient(_SpaceClientEventMixin):
     ) -> A2APlatformTask:
         agent = await self._resolve_agent(agent_id)
         normalized = self._normalize_initial_message(message)
-        prepared = await self._backend.prepare_call(
-            space_id=self._space_id,
-            target_agent_id=agent.agent_id,
-            expected_version_id=agent.version_id,
-            message_id=normalized.message_id,
-            message_sha256=_canonical_sha256(normalized),
-            idempotency_token=idempotency_token or f"idem-{uuid.uuid4().hex}",
-        )
+        token = idempotency_token or f"idem-{uuid.uuid4().hex}"
+        deadline = time.monotonic() + INITIAL_SEND_BIND_WAIT_SECONDS
+        while True:
+            try:
+                prepared = await self._backend.prepare_call(
+                    space_id=self._space_id,
+                    target_agent_id=agent.agent_id,
+                    expected_version_id=agent.version_id,
+                    message_id=normalized.message_id,
+                    message_sha256=_canonical_sha256(normalized),
+                    idempotency_token=token,
+                )
+                break
+            except A2AControlPlaneError as exc:
+                if exc.error_code != "A2A_INITIAL_SEND_PENDING" or time.monotonic() >= deadline:
+                    raise
+                await asyncio.sleep(min(0.5, max(0.0, deadline - time.monotonic())))
         self._validate_prepared_target(agent, prepared)
+        if prepared.remote_task is not None:
+            # The control plane resolved this idempotency key to an existing
+            # task. Its send permit is bound to that remote task, so replaying
+            # the initial message would be rejected by the Gateway.
+            self._agents_by_task[prepared.platform_task_id] = agent
+            await self._record_agent_for_task(prepared.platform_task_id, agent)
+            return await self.get_task(prepared.platform_task_id)
         handle = await self._send_prepared_message(
             prepared,
             agent,
@@ -323,6 +391,16 @@ class A2ASpaceClient(_SpaceClientEventMixin):
     ) -> A2APlatformTask:
         require_a2a_resource_id(task_id, "a2a-task-", field_name="task_id")
         normalized = self._normalize_initial_message(message)
+        # Resolve the durable binding before hashing the final continuation wire
+        # message. The send permit binds the hash including task/context IDs.
+        binding = await self._backend.prepare_task_operation(
+            platform_task_id=task_id, operation="get_task"
+        )
+        self._validate_prepared_ids(binding)
+        remote_task = self._require_remote_task(binding)
+        normalized.task_id = remote_task.remote_task_id
+        if remote_task.remote_context_id:
+            normalized.context_id = remote_task.remote_context_id
         prepared = await self._backend.prepare_task_operation(
             platform_task_id=task_id,
             operation="send_message",
@@ -331,10 +409,8 @@ class A2ASpaceClient(_SpaceClientEventMixin):
             idempotency_token=idempotency_token or f"idem-{uuid.uuid4().hex}",
         )
         self._validate_prepared_ids(prepared)
-        remote_task = self._require_remote_task(prepared)
-        normalized.task_id = remote_task.remote_task_id
-        if remote_task.remote_context_id:
-            normalized.context_id = remote_task.remote_context_id
+        if self._require_remote_task(prepared) != remote_task:
+            raise RuntimeError("A2A_REMOTE_BINDING_CONFLICT")
         agent = self._agent_from_prepared(prepared)
         return await self._send_prepared_message(
             prepared,
@@ -603,7 +679,11 @@ class A2ASpaceClient(_SpaceClientEventMixin):
         cached = self._agents_by_id.get(prepared.target.agent_id)
         if cached is not None and cached.version_id == prepared.target.version_id:
             return cached
-        card = self._route_only_card(prepared.target.agent_id, prepared.target.version_id)
+        card = self._route_only_card(
+            prepared.target.agent_id,
+            prepared.target.version_id,
+            streaming=prepared.route.streaming,
+        )
         return DiscoveredAgent(
             agent_id=prepared.target.agent_id,
             version_id=prepared.target.version_id,
@@ -613,14 +693,14 @@ class A2ASpaceClient(_SpaceClientEventMixin):
             route_kind=prepared.route.kind,
         )
 
-    def _route_only_card(self, name: str, version: str) -> AgentCard:
+    def _route_only_card(self, name: str, version: str, *, streaming: bool = False) -> AgentCard:
         return ParseDict(
             {
                 "name": name,
                 "description": "AgentEngine prepared A2A route",
                 "version": version,
                 "supportedInterfaces": [],
-                "capabilities": {},
+                "capabilities": {"streaming": streaming},
                 "defaultInputModes": ["text/plain"],
                 "defaultOutputModes": ["text/plain"],
                 "skills": [],
@@ -687,7 +767,12 @@ class A2ASpaceClient(_SpaceClientEventMixin):
             owned_http = None
             if http is None:
                 # 外部调用方需自行传入已配置 verify 的 httpx_client。
-                owned_http = httpx.AsyncClient(trust_env=False)
+                verify = True
+                if prepared.route.kind == "hosted_gateway":
+                    from ksadk.a2a.platform import _gateway_http_verify
+
+                    verify = _gateway_http_verify()
+                owned_http = httpx.AsyncClient(trust_env=False, verify=verify)
                 http = owned_http
             client = await create_client(
                 agent=route_card,

ksadk/a2a/task_adapter.py

@@ -16,6 +16,7 @@ cancel 一律走 G0.3 冻结的 ``RuntimeAdapter.cancel``(含 pending-cancel 语
 from __future__ import annotations
 
 import logging
+import os
 from collections.abc import AsyncIterator, Mapping
 from typing import Any, Optional
 
@@ -140,16 +141,31 @@ class A2ARuntimeTaskAdapter:
         input_data: Any,
     ) -> RunHandle:
         """通过 RuntimeAdapter 启动 A2A task,返回后续共用的真实 handle。"""
-        await self.prepare_context(context)
+        session_id = await self.prepare_context(context)
         context_metadata = self._as_dict(getattr(context, "metadata", None))
         context_metadata.pop("user_id", None)
         context_metadata.pop("agent_id", None)
         tenant = self._trusted_tenant(context)
+        from ksadk.sessions import resolve_session_service
+
+        service = resolve_session_service()
+        call_context = getattr(context, "call_context", None)
+        state = getattr(call_context, "state", None)
+        identity = state.get("a2a_identity") if isinstance(state, Mapping) else None
+        agent_id = (
+            str(identity.target_agent_id).strip()
+            if isinstance(identity, A2AIngressIdentity)
+            else os.environ.get("KSADK_A2A_AGENT_ID", "").strip()
+        )
+        if agent_id:
+            existing = await service.get_session_metadata(session_id)
+            if existing is None:
+                await service.create_session(agent_id, tenant, session_id=session_id)
         handle = await self._adapter.start(
             StartRequest(
                 input=input_data,
                 user_id=tenant,
-                session_id=self._extract_session_id(context),
+                session_id=session_id,
                 agent_id=None,
                 metadata={**context_metadata, "invocation_id": task_id},
             )
@@ -374,9 +390,7 @@ class A2ARuntimeTaskAdapter:
     @classmethod
     def _resume_payload(cls, state: A2AResumeState, *, answer: Any) -> ResumePayload:
         data = (
-            cls._approval_decision(answer)
-            if state.payload_kind == "approval_decision"
-            else answer
+            cls._approval_decision(answer) if state.payload_kind == "approval_decision" else answer
         )
         return ResumePayload(kind=state.payload_kind, call_id=state.call_id, data=data)
 

ksadk/a2a/task_event_dispatcher.py

@@ -10,6 +10,17 @@ from ksadk.a2a.task_event_outbox import A2ATaskEventOutbox
 
 logger = logging.getLogger(__name__)
 
+PERMANENT_TASK_EVENT_ERRORS = frozenset(
+    {
+        "A2A_EVENT_BATCH_TOO_LARGE",
+        "A2A_KERNEL_FACT_INVALID",
+        "A2A_EVENT_REF_CAPACITY",
+        "A2A_EVENT_REF_CONFLICT",
+        "A2A_EVENT_REF_INVALID",
+        "A2A_TASK_NOT_FOUND",
+    }
+)
+
 
 class A2ATaskEventSink(Protocol):
     async def append_task_events(
@@ -45,6 +56,7 @@ class A2ATaskEventDispatcher:
         self._background_task: asyncio.Task[None] | None = None
         self._started = False
         self._last_error: str | None = None
+        self._permanent_error: str | None = None
 
     @property
     def outbox(self) -> A2ATaskEventOutbox:
@@ -124,7 +136,15 @@ class A2ATaskEventDispatcher:
             while True:
                 batches = await self._outbox.pending(limit=100)
                 if not batches:
-                    self._last_error = None
+                    # A background drain may have dead-lettered a batch before
+                    # an explicit flush acquires this lock. Empty pending work
+                    # is not proof that every queued batch was delivered.
+                    self._last_error = self._permanent_error
+                    if raise_on_error and self._permanent_error:
+                        raise RuntimeError(
+                            "A2A task event delivery was permanently rejected: "
+                            + self._permanent_error
+                        )
                     return delivered
                 for batch in batches:
                     try:
@@ -139,6 +159,19 @@ class A2ATaskEventDispatcher:
                         error = str(getattr(exc, "error_code", "") or type(exc).__name__)
                         self._last_error = error
                         await self._outbox.record_failure(batch.batch_id, error)
+                        if error in PERMANENT_TASK_EVENT_ERRORS:
+                            await self._outbox.dead_letter(batch.batch_id, error)
+                            self._permanent_error = error
+                            logger.error(
+                                "A2A task event batch was permanently rejected and moved "
+                                "to dead letters: task=%s batch=%s error=%s",
+                                batch.platform_task_id,
+                                batch.batch_id,
+                                error,
+                            )
+                            if raise_on_error:
+                                raise
+                            continue
                         if raise_on_error:
                             raise
                         logger.warning(
@@ -164,4 +197,8 @@ class A2ATaskEventDispatcher:
                 self._wake_event.clear()
 
 
-__all__ = ["A2ATaskEventDispatcher", "A2ATaskEventSink"]
+__all__ = [
+    "A2ATaskEventDispatcher",
+    "A2ATaskEventSink",
+    "PERMANENT_TASK_EVENT_ERRORS",
+]

ksadk/a2a/task_event_outbox.py

@@ -12,6 +12,9 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncEngine
+
 ENV_A2A_EVENT_OUTBOX_PATH = "KSADK_A2A_EVENT_OUTBOX_PATH"
 DEFAULT_A2A_EVENT_OUTBOX_PATH = ".agentengine/a2a_event_outbox.sqlite3"
 
@@ -57,6 +60,12 @@ class A2ATaskEventOutbox(ABC):
     async def record_failure(self, batch_id: str, error: str) -> None:
         raise NotImplementedError
 
+    @abstractmethod
+    async def dead_letter(self, batch_id: str, error: str) -> None:
+        """Preserve a permanently rejected batch outside the live FIFO."""
+
+        raise NotImplementedError
+
 
 def _serialize_events(events: list[dict[str, Any]]) -> str:
     return json.dumps(events, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
@@ -72,6 +81,7 @@ class InMemoryA2ATaskEventOutbox(A2ATaskEventOutbox):
 
     def __init__(self) -> None:
         self._batches: dict[str, A2ATaskEventBatch] = {}
+        self._dead_letters: dict[str, tuple[A2ATaskEventBatch, str]] = {}
         self._lock = asyncio.Lock()
         self._next_sequence = 0
 
@@ -120,6 +130,12 @@ class InMemoryA2ATaskEventOutbox(A2ATaskEventOutbox):
                     attempt_count=batch.attempt_count + 1,
                 )
 
+    async def dead_letter(self, batch_id: str, error: str) -> None:
+        async with self._lock:
+            batch = self._batches.pop(batch_id, None)
+            if batch is not None:
+                self._dead_letters[batch_id] = (batch, error[:512])
+
 
 class SQLiteA2ATaskEventOutbox(A2ATaskEventOutbox):
     """SQLite adapter with stable batch IDs and crash-safe acknowledgement."""
@@ -178,6 +194,20 @@ class SQLiteA2ATaskEventOutbox(A2ATaskEventOutbox):
                 )
                 """
             )
+            connection.execute(
+                """
+                CREATE TABLE IF NOT EXISTS a2a_task_event_dead_letters (
+                    sequence INTEGER NOT NULL,
+                    batch_id TEXT PRIMARY KEY,
+                    platform_task_id TEXT NOT NULL,
+                    events_json TEXT NOT NULL,
+                    created_at TEXT NOT NULL,
+                    attempt_count INTEGER NOT NULL,
+                    last_error TEXT NOT NULL,
+                    dead_lettered_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+                )
+                """
+            )
             connection.execute(
                 """
                 INSERT OR IGNORE INTO a2a_task_event_outbox_sequence(sequence)
@@ -250,6 +280,10 @@ class SQLiteA2ATaskEventOutbox(A2ATaskEventOutbox):
             (error[:512], batch_id),
         )
 
+    async def dead_letter(self, batch_id: str, error: str) -> None:
+        await self.initialize()
+        await asyncio.to_thread(self._dead_letter_sync, batch_id, error[:512])
+
     def _execute(self, statement: str, params: tuple[Any, ...]) -> None:
         connection = sqlite3.connect(self._path, timeout=5)
         try:
@@ -298,6 +332,35 @@ class SQLiteA2ATaskEventOutbox(A2ATaskEventOutbox):
         finally:
             connection.close()
 
+    def _dead_letter_sync(self, batch_id: str, error: str) -> None:
+        connection = sqlite3.connect(self._path, timeout=5, isolation_level=None)
+        try:
+            connection.execute("PRAGMA synchronous=FULL")
+            connection.execute("BEGIN IMMEDIATE")
+            connection.execute(
+                """
+                INSERT OR IGNORE INTO a2a_task_event_dead_letters(
+                    sequence, batch_id, platform_task_id, events_json, created_at,
+                    attempt_count, last_error
+                )
+                SELECT sequence, batch_id, platform_task_id, events_json, created_at,
+                       attempt_count, ?
+                FROM a2a_task_event_outbox
+                WHERE batch_id = ?
+                """,
+                (error, batch_id),
+            )
+            connection.execute(
+                "DELETE FROM a2a_task_event_outbox WHERE batch_id = ?",
+                (batch_id,),
+            )
+            connection.execute("COMMIT")
+        except BaseException:
+            connection.rollback()
+            raise
+        finally:
+            connection.close()
+
     def _pending_sync(self, limit: int) -> list[tuple[Any, ...]]:
         connection = sqlite3.connect(self._path, timeout=5)
         try:
@@ -316,11 +379,163 @@ class SQLiteA2ATaskEventOutbox(A2ATaskEventOutbox):
             connection.close()
 
 
+class PostgresA2ATaskEventOutbox(A2ATaskEventOutbox):
+    """Shared ordered outbox for multi-replica managed Runtimes."""
+
+    def __init__(self, engine: AsyncEngine) -> None:
+        self._engine = engine
+
+    async def initialize(self) -> None:
+        async with self._engine.begin() as connection:
+            await connection.execute(
+                text(
+                    """
+                    CREATE TABLE IF NOT EXISTS ksadk_a2a_task_event_outbox (
+                        sequence BIGSERIAL PRIMARY KEY,
+                        batch_id TEXT NOT NULL UNIQUE,
+                        platform_task_id TEXT NOT NULL,
+                        events_json TEXT NOT NULL,
+                        created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+                        attempt_count INTEGER NOT NULL DEFAULT 0,
+                        last_error TEXT
+                    )
+                    """
+                )
+            )
+            await connection.execute(
+                text(
+                    """
+                    CREATE TABLE IF NOT EXISTS ksadk_a2a_task_event_dead_letters (
+                        sequence BIGINT NOT NULL,
+                        batch_id TEXT PRIMARY KEY,
+                        platform_task_id TEXT NOT NULL,
+                        events_json TEXT NOT NULL,
+                        created_at TIMESTAMPTZ NOT NULL,
+                        attempt_count INTEGER NOT NULL,
+                        last_error TEXT NOT NULL,
+                        dead_lettered_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
+                    )
+                    """
+                )
+            )
+            await connection.execute(
+                text(
+                    "CREATE INDEX IF NOT EXISTS ix_ksadk_a2a_outbox_created "
+                    "ON ksadk_a2a_task_event_outbox(sequence)"
+                )
+            )
+
+    async def ensure_writable(self) -> None:
+        await self.initialize()
+        async with self._engine.begin() as connection:
+            await connection.execute(
+                text("LOCK TABLE ksadk_a2a_task_event_outbox IN ROW EXCLUSIVE MODE")
+            )
+
+    async def enqueue(
+        self,
+        *,
+        platform_task_id: str,
+        events: list[dict[str, Any]],
+    ) -> str:
+        events_json = _serialize_events(events)
+        batch_id = _batch_id(platform_task_id, events_json)
+        async with self._engine.begin() as connection:
+            await connection.execute(
+                text(
+                    """
+                    INSERT INTO ksadk_a2a_task_event_outbox(
+                        batch_id, platform_task_id, events_json
+                    ) VALUES (:batch_id, :platform_task_id, :events_json)
+                    ON CONFLICT(batch_id) DO NOTHING
+                    """
+                ),
+                {
+                    "batch_id": batch_id,
+                    "platform_task_id": platform_task_id,
+                    "events_json": events_json,
+                },
+            )
+        return batch_id
+
+    async def pending(self, *, limit: int = 100) -> list[A2ATaskEventBatch]:
+        async with self._engine.connect() as connection:
+            result = await connection.execute(
+                text(
+                    """
+                    SELECT sequence, batch_id, platform_task_id, events_json, attempt_count
+                    FROM ksadk_a2a_task_event_outbox
+                    ORDER BY sequence
+                    LIMIT :limit
+                    """
+                ),
+                {"limit": limit},
+            )
+            rows = result.fetchall()
+        return [
+            A2ATaskEventBatch(
+                sequence=int(row[0]),
+                batch_id=str(row[1]),
+                platform_task_id=str(row[2]),
+                events=list(json.loads(str(row[3]))),
+                attempt_count=int(row[4]),
+            )
+            for row in rows
+        ]
+
+    async def acknowledge(self, batch_id: str) -> None:
+        async with self._engine.begin() as connection:
+            await connection.execute(
+                text("DELETE FROM ksadk_a2a_task_event_outbox WHERE batch_id = :batch_id"),
+                {"batch_id": batch_id},
+            )
+
+    async def record_failure(self, batch_id: str, error: str) -> None:
+        async with self._engine.begin() as connection:
+            await connection.execute(
+                text(
+                    """
+                    UPDATE ksadk_a2a_task_event_outbox
+                    SET attempt_count = attempt_count + 1, last_error = :error
+                    WHERE batch_id = :batch_id
+                    """
+                ),
+                {"batch_id": batch_id, "error": error[:512]},
+            )
+
+    async def dead_letter(self, batch_id: str, error: str) -> None:
+        async with self._engine.begin() as connection:
+            await connection.execute(
+                text(
+                    """
+                    INSERT INTO ksadk_a2a_task_event_dead_letters(
+                        sequence, batch_id, platform_task_id, events_json, created_at,
+                        attempt_count, last_error
+                    )
+                    SELECT sequence, batch_id, platform_task_id, events_json, created_at,
+                           attempt_count, :error
+                    FROM ksadk_a2a_task_event_outbox
+                    WHERE batch_id = :batch_id
+                    ON CONFLICT(batch_id) DO NOTHING
+                    """
+                ),
+                {"batch_id": batch_id, "error": error[:512]},
+            )
+            await connection.execute(
+                text(
+                    "DELETE FROM ksadk_a2a_task_event_outbox "
+                    "WHERE batch_id = :batch_id"
+                ),
+                {"batch_id": batch_id},
+            )
+
+
 __all__ = [
     "A2ATaskEventBatch",
     "A2ATaskEventOutbox",
     "DEFAULT_A2A_EVENT_OUTBOX_PATH",
     "ENV_A2A_EVENT_OUTBOX_PATH",
     "InMemoryA2ATaskEventOutbox",
+    "PostgresA2ATaskEventOutbox",
     "SQLiteA2ATaskEventOutbox",
 ]