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

ksadk/agui/agent.py

@@ -7,6 +7,7 @@ import copy
 import hashlib
 import json
 import logging
+import time
 from dataclasses import dataclass, field
 from importlib import import_module
 from typing import Any, AsyncIterator, Callable, Mapping, Optional, cast
@@ -36,12 +37,34 @@ from ag_ui.core import (
     ToolCallStartEvent,
 )
 
-from ksadk.agui.a2ui_projection import project_a2ui_operations
+from ksadk.agui import _agent_helpers
 from ksadk.conversations.runtime_metadata import (
     _update_session_metadata_after_assistant_turn,
     prime_session_metadata_for_user_turn,
 )
-from ksadk.events.runtime_event import EventType, RuntimeEvent
+from ksadk.events.canonical import (
+    ApprovalResponse,
+    ContentSnapshot,
+    ContinuationCreated,
+    InteractionRequested,
+    InteractionResolved,
+    ItemCompleted,
+    ItemSnapshotReplaced,
+    ItemStarted,
+    ItemUpdated,
+    RunCanceled,
+    RunCompleted,
+    RunFailed,
+    RunInterrupted,
+    RunStarted,
+    RuntimeEvent,
+    SourceRef,
+)
+from ksadk.events.content import (
+    TextContent,
+    ToolCallContent,
+    ToolResultContent,
+)
 from ksadk.runtime.adapter import (
     CancelResult,
     ResumePayload,
@@ -105,6 +128,7 @@ class _WireState:
     reasoning_open: bool = False
     terminal: bool = False
     text_content: str = ""
+    reasoning_content: str = ""
 
 
 class KsadkAGUIAgent:
@@ -143,6 +167,12 @@ class KsadkAGUIAgent:
         return type(self)(name=self.name, _shared=self._shared)
 
     async def run(self, input: RunAgentInput) -> AsyncIterator[BaseEvent]:
+        from ksadk.kernel import ingress as _kernel_ingress
+
+        if _kernel_ingress.kernel_route_active():
+            async for event in self._kernel_run(input):
+                yield event
+            return
         wire = _WireState(
             thread_id=input.thread_id,
             run_id=input.run_id,
@@ -170,7 +200,10 @@ class KsadkAGUIAgent:
 
             run.active = True
             async for runtime_event in self._shared.executor.stream(run.handle):
-                persisted = await self._persist(self._event_for_persistence(runtime_event, run))
+                persisted = await self._persist(
+                    self._event_for_persistence(runtime_event, run),
+                    session_id=input.thread_id,
+                )
                 async for event in self._project(persisted, wire, run):
                     yield event
             if not wire.terminal:
@@ -202,6 +235,102 @@ class KsadkAGUIAgent:
             if run is not None and not run.cancel_failed:
                 run.active = False
 
+    async def _kernel_run(self, input: RunAgentInput) -> AsyncIterator[BaseEvent]:
+        """kernel 路径（灰度 opt-in）：AG-UI run -> AgentControlCommand -> receipt。
+
+        mutation 只走 kernel.submit；AG-UI 事件 shape 保留，cursor 源自同一
+        Session seq（SessionEventSubscription.after_seq）。
+        """
+        from ksadk.kernel import ingress as _kernel_ingress
+
+        yield RunStartedEvent(
+            thread_id=input.thread_id,
+            run_id=input.run_id,
+            parent_run_id=input.parent_run_id,
+            input=input,
+        )
+        message_id = f"{input.run_id}:assistant"
+        text = ""
+        try:
+            trusted = _kernel_ingress.trusted_context(
+                source_kind="agui",
+                source_ref=input.run_id,
+                session_id=input.thread_id,
+                operations=("enqueue",),
+                launch_context=self._shared.launch_context,
+            )
+            command = _kernel_ingress.map_agui_request(
+                session_id=input.thread_id,
+                idempotency_key=input.run_id,
+                content=[
+                    {"role": "user", "content": _agui_user_text(input)}
+                ],
+                run_id=input.run_id,
+                trusted=trusted,
+            )
+            receipt = await _kernel_ingress.submit_command(
+                command, permit=trusted.permit
+            )
+            if receipt.status not in ("accepted", "duplicate"):
+                yield RunErrorEvent(
+                    message=f"agent kernel rejected command: {receipt.status}",
+                    code=receipt.status.upper(),
+                )
+                return
+            text_open = False
+            async for _seq, payload in _kernel_ingress.subscribe_projected(
+                input.thread_id,
+                trusted=trusted,
+                after_seq=int(receipt.accepted_seq or 0),
+                projector=_agui_envelope_payload,
+            ):
+                if payload is None:
+                    continue
+                kind, value = payload
+                if kind == "delta":
+                    if not text_open:
+                        text_open = True
+                        yield TextMessageStartEvent(message_id=message_id)
+                    text += value
+                    yield TextMessageContentEvent(message_id=message_id, delta=value)
+                elif kind == "completed":
+                    final = value or text
+                    if final and not text_open:
+                        text_open = True
+                        yield TextMessageStartEvent(message_id=message_id)
+                    if final.startswith(text) and len(final) > len(text):
+                        yield TextMessageContentEvent(
+                            message_id=message_id, delta=final[len(text):]
+                        )
+                    text = final
+                    if text_open:
+                        yield TextMessageEndEvent(message_id=message_id)
+                    yield RunFinishedEvent(
+                        thread_id=input.thread_id,
+                        run_id=input.run_id,
+                        outcome=RunFinishedSuccessOutcome(),
+                        result={"output_text": text},
+                    )
+                    return
+            if text_open:
+                yield TextMessageEndEvent(message_id=message_id)
+            yield RunFinishedEvent(
+                thread_id=input.thread_id,
+                run_id=input.run_id,
+                outcome=RunFinishedSuccessOutcome(),
+                result={"output_text": text},
+            )
+        except Exception:
+            logger.exception(
+                "AG-UI kernel ingress failed for thread=%s run=%s",
+                input.thread_id,
+                input.run_id,
+            )
+            yield RunErrorEvent(
+                message="Agent kernel ingress failed",
+                code="KERNEL_ERROR",
+            )
+
     async def _resolve_run(self, input: RunAgentInput) -> tuple[_ThreadRun, bool]:
         async with self._shared.lock:
             if input.resume:
@@ -331,155 +460,183 @@ class KsadkAGUIAgent:
                 default=str,
             )
             decision = self._approval_decision_for_audit(entry.status, entry.payload)
-            event = RuntimeEvent.create(
-                EventType.APPROVAL_RESOLVED,
+            event = InteractionResolved(
+                schema_version=2,
                 event_id=f"evt_agui_resume_{hashlib.sha256(event_key.encode()).hexdigest()}",
-                agent_id=str(run.handle.native_ref.get("agent_id") or self.name),
-                user_id=str(run.handle.native_ref.get("user_id") or "agui-user"),
-                session_id=input.thread_id,
-                invocation_id=run.handle.run_id,
-                seq_id=0,
-                payload={
-                    "approval_id": entry.interrupt_id,
-                    "call_id": entry.interrupt_id,
-                    "decision": decision,
-                    "resume_fingerprint": fingerprint,
-                    "protocol": "ag-ui",
-                },
+                seq=0,
+                timestamp=time.time(),
+                run_id=run.handle.run_id,
+                scope_id=f"ksadk:{run.handle.run_id}",
+                source=SourceRef(
+                    framework="ksadk",
+                    metadata={
+                        "agent_id": str(run.handle.native_ref.get("agent_id") or self.name),
+                        "user_id": str(run.handle.native_ref.get("user_id") or "agui-user"),
+                        "session_id": input.thread_id,
+                        "protocol": "ag-ui",
+                        "resume_fingerprint": fingerprint,
+                    },
+                ),
+                interaction_id=entry.interrupt_id,
+                interaction_kind="approval",
+                response=ApprovalResponse(
+                    response_type="approval",
+                    decision=(
+                        decision if decision in ("approved", "rejected", "canceled") else "rejected"
+                    ),
+                    data={"call_id": entry.interrupt_id},
+                ),
             )
             if index == 0:
-                _persisted, reservation_created = await self._reserve(event)
+                _persisted, reservation_created = await self._reserve(
+                    event, session_id=input.thread_id
+                )
                 if not reservation_created:
                     return False
             else:
-                await self._persist(event)
+                await self._persist(event, session_id=input.thread_id)
         return reservation_created
 
-    @staticmethod
-    def _approval_decision_for_audit(status: str, payload: Any) -> str:
-        """Persist a stable decision value while accepting official AG-UI envelopes."""
-
-        if status != "resolved":
-            return "rejected"
-        if payload is True:
-            return "approved"
-        if isinstance(payload, Mapping):
-            for key in ("approve", "approved"):
-                if key in payload:
-                    return "approved" if bool(payload[key]) else "rejected"
-            for key in ("decision", "type"):
-                if key in payload:
-                    return KsadkAGUIAgent._approval_decision_for_audit(status, payload[key])
-            return "rejected"
-        if isinstance(payload, str) and payload.strip().lower() in {"approve", "approved"}:
-            return "approved"
-        return "rejected"
-
     async def _project(
         self,
         event: RuntimeEvent,
         wire: _WireState,
         run: _ThreadRun,
     ) -> AsyncIterator[BaseEvent]:
-        payload = event.payload
-        event_type = event.event_type
-
-        if event_type in (EventType.TEXT_DELTA, EventType.TEXT_COMPLETED):
+        # ---- message (text) ----
+        if isinstance(event, (ItemUpdated, ItemSnapshotReplaced)) and event.item_kind == "message":
             if not wire.text_open:
                 wire.text_open = True
                 yield TextMessageStartEvent(message_id=wire.message_id)
-            text = str(payload.get("text") or "")
-            if event_type == EventType.TEXT_COMPLETED and wire.text_content:
-                text = text[len(wire.text_content) :] if text.startswith(wire.text_content) else ""
+            if isinstance(event, ItemSnapshotReplaced):
+                # atomic snapshot replace: close and reopen with full text
+                wire.text_open = False
+                wire.text_content = ""
+                yield TextMessageEndEvent(message_id=wire.message_id)
+                wire.text_open = True
+                yield TextMessageStartEvent(message_id=wire.message_id)
+                text = self._extract_text(event.snapshot)
+            elif event.op == "replace":
+                wire.text_open = False
+                wire.text_content = ""
+                yield TextMessageEndEvent(message_id=wire.message_id)
+                wire.text_open = True
+                yield TextMessageStartEvent(message_id=wire.message_id)
+                text = event.update.text if isinstance(event.update, TextContent) else ""
+            else:
+                text = event.update.text if isinstance(event.update, TextContent) else ""
             if text:
                 yield TextMessageContentEvent(message_id=wire.message_id, delta=text)
                 wire.text_content += text
-            if event_type == EventType.TEXT_COMPLETED:
-                wire.text_open = False
-                yield TextMessageEndEvent(message_id=wire.message_id)
             return
 
-        if event_type in (EventType.REASONING_DELTA, EventType.REASONING_COMPLETED):
+        if isinstance(event, ItemCompleted) and event.item_kind == "message":
+            if not wire.text_open:
+                wire.text_open = True
+                yield TextMessageStartEvent(message_id=wire.message_id)
+            # ItemCompleted is the authoritative snapshot; do NOT re-append
+            # the full text when deltas already covered the content.
+            if not wire.text_content:
+                text = self._extract_text(event.snapshot)
+                if text:
+                    yield TextMessageContentEvent(message_id=wire.message_id, delta=text)
+                    wire.text_content += text
+            wire.text_open = False
+            yield TextMessageEndEvent(message_id=wire.message_id)
+            return
+
+        if isinstance(event, ItemStarted) and event.item_kind == "message":
+            # ItemStarted for messages is a tracking signal; the text message
+            # opens lazily on the first content delta or completed snapshot.
+            return
+
+        # ---- reasoning ----
+        if (
+            isinstance(event, (ItemUpdated, ItemSnapshotReplaced))
+            and event.item_kind == "reasoning"
+        ):
             if not wire.reasoning_open:
                 wire.reasoning_open = True
                 yield ReasoningStartEvent(message_id=wire.reasoning_id)
                 yield ReasoningMessageStartEvent(message_id=wire.reasoning_id, role="reasoning")
-            text = str(payload.get("text") or "")
+            if isinstance(event, ItemSnapshotReplaced):
+                wire.reasoning_content = ""
+                text = self._extract_text(event.snapshot)
+            else:
+                text = event.update.text if isinstance(event.update, TextContent) else ""
             if text:
                 yield ReasoningMessageContentEvent(message_id=wire.reasoning_id, delta=text)
-            if event_type == EventType.REASONING_COMPLETED:
-                wire.reasoning_open = False
-                yield ReasoningMessageEndEvent(message_id=wire.reasoning_id)
-                yield ReasoningEndEvent(message_id=wire.reasoning_id)
+                wire.reasoning_content += text
             return
 
-        if event_type == EventType.TOOL_CALL_BEGIN:
-            call_id = str(payload.get("call_id") or "tool")
-            yield ToolCallStartEvent(
-                tool_call_id=call_id,
-                tool_call_name=str(payload.get("name") or "tool"),
-                parent_message_id=wire.message_id,
-            )
-            if "args" in payload:
+        if isinstance(event, ItemCompleted) and event.item_kind == "reasoning":
+            if not wire.reasoning_open:
+                wire.reasoning_open = True
+                yield ReasoningStartEvent(message_id=wire.reasoning_id)
+                yield ReasoningMessageStartEvent(message_id=wire.reasoning_id, role="reasoning")
+            if not wire.reasoning_content:
+                text = self._extract_text(event.snapshot)
+                if text:
+                    yield ReasoningMessageContentEvent(message_id=wire.reasoning_id, delta=text)
+                    wire.reasoning_content += text
+            wire.reasoning_open = False
+            yield ReasoningMessageEndEvent(message_id=wire.reasoning_id)
+            yield ReasoningEndEvent(message_id=wire.reasoning_id)
+            return
+
+        if isinstance(event, ItemStarted) and event.item_kind == "reasoning":
+            return
+
+        # ---- tool call ----
+        if isinstance(event, ItemStarted) and event.item_kind == "tool_call":
+            part = self._first_part(event.initial)
+            if isinstance(part, ToolCallContent):
+                call_id = part.call_id
+                yield ToolCallStartEvent(
+                    tool_call_id=call_id,
+                    tool_call_name=part.name,
+                    parent_message_id=wire.message_id,
+                )
                 yield ToolCallArgsEvent(
                     tool_call_id=call_id,
-                    delta=json.dumps(payload.get("args"), ensure_ascii=False, default=str),
+                    delta=json.dumps(part.arguments, ensure_ascii=False, default=str),
                 )
             return
 
-        if event_type == EventType.TOOL_CALL_END:
-            call_id = str(payload.get("call_id") or "tool")
-            content = (
-                payload.get("result") if payload.get("error") is None else payload.get("error")
-            )
-            # AG-UI closes the active call at TOOL_CALL_END.  Sending a result
-            # first makes official clients discard the call, then reject this
-            # end event as orphaned.
+        if isinstance(event, ItemCompleted) and event.item_kind == "tool_call":
+            part = self._first_part(event.snapshot)
+            call_id = part.call_id if isinstance(part, ToolCallContent) else "tool"
             yield ToolCallEndEvent(tool_call_id=call_id)
-            yield ToolCallResultEvent(
-                message_id=f"{wire.run_id}:tool:{call_id}",
-                tool_call_id=call_id,
-                content=json.dumps(content, ensure_ascii=False, default=str),
-                role="tool",
-            )
             return
 
-        if event_type == EventType.CHECKPOINT_CREATED:
-            yield StateSnapshotEvent(snapshot={"checkpoint": copy.deepcopy(payload)})
+        if isinstance(event, ItemCompleted) and event.item_kind == "tool_result":
+            part = self._first_part(event.snapshot)
+            if isinstance(part, ToolResultContent):
+                call_id = part.call_id
+                content = part.result
+                yield ToolCallResultEvent(
+                    message_id=f"{wire.run_id}:tool:{call_id}",
+                    tool_call_id=call_id,
+                    content=json.dumps(content, ensure_ascii=False, default=str),
+                    role="tool",
+                )
             return
 
-        if event_type == EventType.APPROVAL_REQUESTED:
-            interrupt_id = str(payload.get("approval_id") or payload.get("call_id") or "")
-            checkpoint_id = str(run.handle.native_ref.get("checkpoint_id") or "")
-            if not checkpoint_id:
-                known = run.handle.native_ref.get("known_checkpoint_ids") or []
-                checkpoint_id = str(known[-1]) if known else ""
-            raw_detail = payload.get("detail")
-            detail: dict[str, Any] = raw_detail if isinstance(raw_detail, dict) else {}
-            interrupt = Interrupt(
-                id=interrupt_id,
-                reason=str(detail.get("reason") or payload.get("kind") or "approval"),
-                message=self._approval_message(detail, payload),
-                tool_call_id=str(payload.get("call_id") or "") or None,
-                response_schema=detail.get("response_schema"),
-                metadata=self._approval_metadata(detail, payload),
-            )
-            run.pending[interrupt_id] = _PendingInterrupt(interrupt, checkpoint_id)
+        if isinstance(event, ItemStarted) and event.item_kind == "tool_result":
             return
 
-        if event_type in {
-            EventType.A2UI_SURFACE_BEGIN,
-            EventType.A2UI_SURFACE_UPDATE,
-            EventType.A2UI_SURFACE_END,
-        }:
-            operations = project_a2ui_operations(event_type, payload)
+        # ---- A2UI surface (item_kind="data" + source.protocol="a2ui") ----
+        if (
+            isinstance(event, (ItemStarted, ItemUpdated, ItemCompleted))
+            and event.item_kind == "data"
+            and event.source.protocol == "a2ui"
+        ):
+            surface_id = str(event.source.metadata.get("surface_id") or "")
+            operations = self._a2ui_operations(event, surface_id)
             if operations:
-                surface_id = str(payload.get("surface_id") or payload.get("surfaceId") or "")
                 yield ActivitySnapshotEvent(
                     message_id=f"{wire.run_id}:a2ui:{surface_id}",
                     activity_type="a2ui-surface",
-                    # The client renderer addresses a surface by this value.
-                    # ``message_id`` is a transport id, not the A2UI surface id.
                     content={
                         "surfaceId": surface_id,
                         "a2ui_operations": operations,
@@ -488,18 +645,62 @@ class KsadkAGUIAgent:
                 )
             return
 
-        if event_type == EventType.RUN_INTERRUPTED:
+        # ---- checkpoint ----
+        if isinstance(event, ContinuationCreated):
+            # Track checkpoint id in handle native_ref for downstream approval
+            # resolution (pending interrupts need a resumable checkpoint_id).
+            ckpt_id = str(event.ref.get("checkpoint_id") or "")
+            if ckpt_id:
+                run.handle.native_ref["checkpoint_id"] = ckpt_id
+                known = run.handle.native_ref.setdefault("known_checkpoint_ids", [])
+                if ckpt_id not in known:
+                    known.append(ckpt_id)
+            yield StateSnapshotEvent(snapshot={"checkpoint": copy.deepcopy(event.ref)})
+            return
+
+        # ---- approval ----
+        if isinstance(event, InteractionRequested):
+            interrupt = self._interrupt_from_interaction(event)
+            checkpoint_id = str(run.handle.native_ref.get("checkpoint_id") or "")
+            if not checkpoint_id:
+                known = run.handle.native_ref.get("known_checkpoint_ids") or []
+                checkpoint_id = str(known[-1]) if known else ""
+            run.pending[interrupt.id] = _PendingInterrupt(interrupt, checkpoint_id)
+            return
+
+        # ---- run lifecycle ----
+        if isinstance(event, RunInterrupted):
             async for close_event in self._close_open_messages(wire):
                 yield close_event
             if not run.pending:
                 raise ValueError("runtime interrupted without a pending approval")
-            checkpoint_id = str(run.handle.native_ref.get("checkpoint_id") or "")
+            # If checkpoint_id wasn't set by ContinuationCreated (e.g. langgraph
+            # canonical stream without checkpoint_ref on first run), try to
+            # extract it from the RunInterrupted event's continuation_id or
+            # the executor's checkpoint descriptor.
+            if event.continuation_id:
+                checkpoint_id = str(event.continuation_id)
+            else:
+                checkpoint_id = str(run.handle.native_ref.get("checkpoint_id") or "")
             if not checkpoint_id:
                 known = run.handle.native_ref.get("known_checkpoint_ids") or []
                 checkpoint_id = str(known[-1]) if known else ""
-            for pending in run.pending.values():
-                if not pending.checkpoint_id:
-                    pending.checkpoint_id = checkpoint_id
+            if not checkpoint_id:
+                # Last resort: query the executor for the native checkpoint.
+                try:
+                    descriptor = await self._shared.executor.checkpoint(run.handle)
+                    checkpoint_id = str(descriptor.checkpoint_id or "")
+                    if checkpoint_id:
+                        run.handle.native_ref["checkpoint_id"] = checkpoint_id
+                        known = run.handle.native_ref.setdefault("known_checkpoint_ids", [])
+                        if checkpoint_id not in known:
+                            known.append(checkpoint_id)
+                except Exception:
+                    pass
+            if checkpoint_id:
+                for pending in run.pending.values():
+                    if not pending.checkpoint_id:
+                        pending.checkpoint_id = checkpoint_id
             run.interrupted = True
             wire.terminal = True
             yield RunFinishedEvent(
@@ -511,23 +712,30 @@ class KsadkAGUIAgent:
             )
             return
 
-        if event_type == EventType.RUN_COMPLETED:
+        if isinstance(event, RunCompleted):
             async for finish_event in self._finish_success(wire):
                 yield finish_event
             return
 
-        if event_type in (EventType.RUN_FAILED, EventType.RUN_CANCELED):
+        if isinstance(event, RunCanceled):
             async for close_event in self._close_open_messages(wire):
                 yield close_event
             wire.terminal = True
             yield RunErrorEvent(
-                message=(
-                    "Runtime run was cancelled"
-                    if event_type == EventType.RUN_CANCELED
-                    else "Runtime execution failed"
-                ),
-                code=("CANCELLED" if event_type == EventType.RUN_CANCELED else "RUNTIME_ERROR"),
+                message=event.reason or "Runtime run was cancelled",
+                code="CANCELLED",
             )
+            return
+
+        if isinstance(event, RunFailed):
+            async for close_event in self._close_open_messages(wire):
+                yield close_event
+            wire.terminal = True
+            yield RunErrorEvent(
+                message=event.error.message or "Runtime execution failed",
+                code="RUNTIME_ERROR",
+            )
+            return
 
     async def _finish_success(self, wire: _WireState) -> AsyncIterator[BaseEvent]:
         async for event in self._close_open_messages(wire):
@@ -550,14 +758,17 @@ class KsadkAGUIAgent:
             wire.text_open = False
             yield TextMessageEndEvent(message_id=wire.message_id)
 
-    async def _persist(self, event: RuntimeEvent) -> RuntimeEvent:
+    async def _persist(self, event: RuntimeEvent, *, session_id: str = "") -> RuntimeEvent:
         factory = self._shared.event_store_factory
         if factory is None:
             return event
         store = factory()
-        return cast(RuntimeEvent, await store.append_one(event))
+        sid = str(event.source.metadata.get("session_id") or session_id or "")
+        return cast(RuntimeEvent, await store.append_one(sid, event))
 
-    async def _reserve(self, event: RuntimeEvent) -> tuple[RuntimeEvent, bool]:
+    async def _reserve(
+        self, event: RuntimeEvent, *, session_id: str = ""
+    ) -> tuple[RuntimeEvent, bool]:
         factory = self._shared.event_store_factory
         if factory is None:
             return event, True
@@ -566,7 +777,8 @@ class KsadkAGUIAgent:
         if callable(reserve):
             persisted, created = await reserve(event)
             return cast(RuntimeEvent, persisted), bool(created)
-        return cast(RuntimeEvent, await store.append_one(event)), True
+        sid = str(event.source.metadata.get("session_id") or session_id or "")
+        return cast(RuntimeEvent, await store.append_one(sid, event)), True
 
     async def _persist_user_input(
         self,
@@ -576,21 +788,27 @@ class KsadkAGUIAgent:
     ) -> None:
         event_key = json.dumps([input.thread_id, input.run_id, "user"], ensure_ascii=False)
         await self._persist(
-            RuntimeEvent.create(
-                EventType.RUN_STARTED,
+            RunStarted(
+                schema_version=2,
                 event_id=f"evt_agui_input_{hashlib.sha256(event_key.encode()).hexdigest()}",
-                agent_id=self.name,
-                user_id=request.user_id,
-                session_id=input.thread_id,
-                invocation_id=input.run_id,
-                seq_id=0,
-                payload={
-                    "status": "in_progress",
-                    "input": self._json_safe(request.input),
-                    "source": "ag-ui",
-                    "runtime_type": handle.runtime_type,
-                },
-            )
+                seq=0,
+                timestamp=time.time(),
+                run_id=input.run_id,
+                scope_id=f"ksadk:{input.run_id}",
+                source=SourceRef(
+                    framework="ksadk",
+                    metadata={
+                        "agent_id": self.name,
+                        "user_id": request.user_id,
+                        "session_id": input.thread_id,
+                        "input": self._json_safe(request.input),
+                        "source": "ag-ui",
+                        "runtime_type": handle.runtime_type,
+                    },
+                ),
+                status="running",
+            ),
+            session_id=input.thread_id,
         )
         await self._prime_session_metadata_for_user_turn(
             session_id=input.thread_id,
@@ -638,21 +856,22 @@ class KsadkAGUIAgent:
             logger.debug("failed to update AG-UI session metadata", exc_info=True)
 
     def _event_for_persistence(self, event: RuntimeEvent, run: _ThreadRun) -> RuntimeEvent:
-        if event.event_type in {
-            EventType.APPROVAL_REQUESTED,
-            EventType.APPROVAL_RESOLVED,
-        }:
-            return event.model_copy(update={"payload": {**event.payload, "protocol": "ag-ui"}})
-        if event.event_type != EventType.RUN_INTERRUPTED:
+        if isinstance(event, (InteractionRequested, InteractionResolved)):
+            new_source = event.source.model_copy(
+                update={"metadata": {**event.source.metadata, "protocol": "ag-ui"}}
+            )
+            return event.model_copy(update={"source": new_source})
+        if not isinstance(event, RunInterrupted):
             return event
-        return event.model_copy(
+        new_source = event.source.model_copy(
             update={
-                "payload": {
-                    **event.payload,
+                "metadata": {
+                    **event.source.metadata,
                     "runtime_handle": self._durable_handle(run.handle),
                 }
             }
         )
+        return event.model_copy(update={"source": new_source})
 
     async def _restore_durable_run(
         self,
@@ -663,13 +882,15 @@ class KsadkAGUIAgent:
         if not events:
             return None, False
         resolved = {
-            str(event.payload.get("approval_id") or event.payload.get("call_id") or ""): event
+            str(event.interaction_id): event
             for event in events
-            if event.event_type == EventType.APPROVAL_RESOLVED
+            if isinstance(event, InteractionResolved)
         }
         if fingerprints and all(interrupt_id in resolved for interrupt_id in fingerprints):
             for interrupt_id, fingerprint in fingerprints.items():
-                persisted = str(resolved[interrupt_id].payload.get("resume_fingerprint") or "")
+                persisted = str(
+                    resolved[interrupt_id].source.metadata.get("resume_fingerprint") or ""
+                )
                 if persisted and persisted != fingerprint:
                     raise ValueError(f"interrupt {interrupt_id!r} was resolved differently")
             return None, True
@@ -677,22 +898,21 @@ class KsadkAGUIAgent:
             raise ValueError("resume set is only partially resolved")
 
         interrupted = next(
-            (event for event in reversed(events) if event.event_type == EventType.RUN_INTERRUPTED),
+            (event for event in reversed(events) if isinstance(event, RunInterrupted)),
             None,
         )
         if interrupted is None:
             return None, False
-        raw_handle = interrupted.payload.get("runtime_handle")
+        raw_handle = interrupted.source.metadata.get("runtime_handle")
         if not isinstance(raw_handle, dict):
             return None, False
         handle = RunHandle.model_validate(raw_handle)
         requests = [
             event
             for event in events
-            if event.invocation_id == interrupted.invocation_id
-            and event.event_type == EventType.APPROVAL_REQUESTED
-            and str(event.payload.get("approval_id") or event.payload.get("call_id") or "")
-            not in resolved
+            if isinstance(event, InteractionRequested)
+            and event.run_id == interrupted.run_id
+            and str(event.interaction_id) not in resolved
         ]
         pending: dict[str, _PendingInterrupt] = {}
         checkpoint_id = str(handle.native_ref.get("checkpoint_id") or "")
@@ -700,7 +920,7 @@ class KsadkAGUIAgent:
             known = handle.native_ref.get("known_checkpoint_ids") or []
             checkpoint_id = str(known[-1]) if known else ""
         for request in requests:
-            interrupt = self._interrupt_from_payload(request.payload)
+            interrupt = self._interrupt_from_interaction(request)
             pending[interrupt.id] = _PendingInterrupt(interrupt, checkpoint_id)
         if not pending:
             return None, False
@@ -721,55 +941,6 @@ class KsadkAGUIAgent:
             return []
         return list(await list_events(session_id))
 
-    @staticmethod
-    def _durable_handle(handle: RunHandle) -> dict[str, Any]:
-        allowed = {
-            "agent_id",
-            "user_id",
-            "checkpoint_id",
-            "known_checkpoint_ids",
-            "pending_approval_ids",
-            "framework_ref",
-            "thread_id",
-            "checkpoint_ns",
-            "resume_thread_id",
-        }
-        native_ref = {key: value for key, value in handle.native_ref.items() if key in allowed}
-        return {
-            "run_id": handle.run_id,
-            "session_id": handle.session_id,
-            "runtime_type": handle.runtime_type,
-            "native_ref": KsadkAGUIAgent._json_safe(native_ref),
-        }
-
-    @staticmethod
-    def _interrupt_from_payload(payload: Mapping[str, Any]) -> Interrupt:
-        interrupt_id = str(payload.get("approval_id") or payload.get("call_id") or "")
-        raw_detail = payload.get("detail")
-        detail = raw_detail if isinstance(raw_detail, dict) else {}
-        return Interrupt(
-            id=interrupt_id,
-            reason=str(detail.get("reason") or payload.get("kind") or "approval"),
-            message=KsadkAGUIAgent._approval_message(detail, payload),
-            tool_call_id=str(payload.get("call_id") or "") or None,
-            response_schema=detail.get("response_schema"),
-            metadata=KsadkAGUIAgent._approval_metadata(detail, payload),
-        )
-
-    @staticmethod
-    def _duplicate_run(input: RunAgentInput) -> _ThreadRun:
-        return _ThreadRun(
-            handle=RunHandle(
-                run_id=input.run_id,
-                session_id=input.thread_id,
-                runtime_type="ag-ui-duplicate",
-            )
-        )
-
-    @staticmethod
-    def _json_safe(value: Any) -> Any:
-        return json.loads(json.dumps(value, ensure_ascii=False, default=str))
-
     async def _close_thread(self, thread_id: str, run: _ThreadRun) -> None:
         try:
             await self._shared.executor.close(run.handle)
@@ -793,80 +964,93 @@ class KsadkAGUIAgent:
             run.active = True
         return result
 
+    @staticmethod
+    def _approval_decision_for_audit(status: str, payload: Any) -> str:
+        return _agent_helpers.approval_decision_for_audit(status, payload)
+
+    @staticmethod
+    def _durable_handle(handle: RunHandle) -> dict[str, Any]:
+        return _agent_helpers.durable_handle(handle)
+
+    @staticmethod
+    def _interrupt_from_payload(payload: Mapping[str, Any]) -> Interrupt:
+        return _agent_helpers.interrupt_from_payload(payload)
+
+    @staticmethod
+    def _interrupt_from_interaction(event: InteractionRequested) -> Interrupt:
+        return _agent_helpers.interrupt_from_interaction(event)
+
+    @staticmethod
+    def _extract_text(snapshot: ContentSnapshot | None) -> str:
+        return _agent_helpers.extract_text(snapshot)
+
+    @staticmethod
+    def _first_part(snapshot: ContentSnapshot | None) -> Any:
+        return _agent_helpers.first_part(snapshot)
+
+    @staticmethod
+    def _a2ui_operations(
+        event: ItemStarted | ItemUpdated | ItemCompleted,
+        surface_id: str,
+    ) -> list[dict[str, Any]]:
+        return _agent_helpers.a2ui_operations(event, surface_id)
+
+    @staticmethod
+    def _duplicate_run(input: RunAgentInput) -> _ThreadRun:
+        return _agent_helpers.duplicate_run(input)
+
+    @staticmethod
+    def _json_safe(value: Any) -> Any:
+        return _agent_helpers.json_safe(value)
+
     @staticmethod
     def _latest_user_input(input: RunAgentInput) -> Any:
-        for message in reversed(input.messages):
-            if getattr(message, "role", None) == "user":
-                return getattr(message, "content", "")
-        return ""
+        return _agent_helpers.latest_user_input(input)
 
     @staticmethod
     def _input_text(value: Any) -> str:
-        if isinstance(value, str):
-            return value.strip()
-        if isinstance(value, Mapping):
-            return str(value.get("text") or value.get("content") or "").strip()
-        return str(value or "").strip()
+        return _agent_helpers.input_text(value)
 
     @staticmethod
     def _approval_action(detail: Mapping[str, Any]) -> Mapping[str, Any]:
-        nested_request = detail.get("approval_requests")
-        actions = (
-            nested_request.get("action_requests")
-            if isinstance(nested_request, Mapping)
-            else detail.get("action_requests")
-        )
-        if isinstance(actions, list):
-            for action in actions:
-                if isinstance(action, Mapping):
-                    return action
-        return {}
+        return _agent_helpers.approval_action(detail)
 
     @staticmethod
     def _approval_metadata(
         detail: Mapping[str, Any],
         payload: Mapping[str, Any],
     ) -> dict[str, Any]:
-        action = KsadkAGUIAgent._approval_action(detail)
-        arguments = (
-            action.get("args")
-            or action.get("arguments")
-            or detail.get("arguments")
-            or detail.get("args")
-            or payload.get("args")
-        )
-        metadata: dict[str, Any] = {
-            "tool_name": str(
-                action.get("name")
-                or detail.get("tool_name")
-                or payload.get("name")
-                or payload.get("kind")
-                or "approval"
-            ),
-            "arguments": arguments if arguments is not None else {},
-        }
-        approval_level = (
-            action.get("approval_level")
-            or detail.get("approval_level")
-            or payload.get("approval_level")
-        )
-        if approval_level:
-            metadata["approval_level"] = str(approval_level)
-        return metadata
+        return _agent_helpers.approval_metadata(detail, payload)
 
     @staticmethod
     def _approval_message(detail: Mapping[str, Any], payload: Mapping[str, Any]) -> str:
-        action = KsadkAGUIAgent._approval_action(detail)
-        return str(
-            action.get("description")
-            or detail.get("message")
-            or payload.get("message")
-            or "Approval required"
-        )
+        return _agent_helpers.approval_message(detail, payload)
 
     @staticmethod
     def _resume_fingerprint(status: str, payload: Any) -> Any:
-        return json.dumps([status, payload], sort_keys=True, ensure_ascii=False, default=str)
+        return _agent_helpers.resume_fingerprint(status, payload)
 
 
 __all__ = ["KsadkAGUIAgent"]
+
+def _agui_user_text(input: RunAgentInput) -> str:
+    parts = []
+    for message in input.messages or []:
+        content = getattr(message, "content", "")
+        if isinstance(content, str):
+            parts.append(content)
+        elif content is not None:
+            parts.append(str(content))
+    return "\n".join(parts)
+
+
+def _agui_envelope_payload(envelope) -> tuple[str, str] | None:
+    """Session envelope -> AG-UI 文本投影；cursor 仍用 envelope.seq。"""
+
+    payload = envelope.payload or {}
+    if envelope.event_type == "run.completed":
+        return "completed", str(payload.get("output_text") or "")
+    text = str(payload.get("delta") or payload.get("text") or "")
+    if text:
+        return "delta", text
+    return None