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

ksadk/server/routes/run.py

@@ -11,25 +11,51 @@ from typing import TYPE_CHECKING, Any
 
 from fastapi.responses import StreamingResponse
 
+from ksadk.conversations.normalize import (
+    normalize_kop_messages,
+    normalize_parts_content,
+    normalize_responses_input,
+)
 from ksadk.conversations.run_kinds import (
     RUN_MODE_BACKGROUND,
     RUN_MODE_FOREGROUND,
-    RUN_TRIGGER_NEW_RUN,
     trigger_from_resume_input,
 )
+from ksadk.conversations.runtime_metadata import prime_session_metadata_for_user_turn
+from ksadk.conversations.runtime_payloads import (
+    build_chat_completions_payload,
+    build_responses_payload,
+    extract_responses_resume_input,
+)
+from ksadk.conversations.runtime_persistence import (
+    append_run_status_event,
+    ensure_conversation_session,
+)
+from ksadk.conversations.runtime_streaming import (
+    stream_runtime_conversation_turn,
+    stream_runtime_responses_conversation_turn,
+)
 
 if TYPE_CHECKING:
-    from ksadk.conversations.runtime_payloads import PreparedConversationTurn
+    pass
 from ksadk.ids import new_run_id
+from ksadk.kernel.ingress import kernel_route_active
+from ksadk.runtime.conversation_execution import (
+    invoke_runtime_conversation_once,
+    iter_runtime_conversation_semantic_events,
+)
 from ksadk.server.api_models import AgentRunRequest
+from ksadk.server.factory import get_runtime_execution
 
 from . import dependencies as deps
 from .checkpoint_resolution import _resolve_checkpoint_resume_input_from_session
 from .common import (
     _action_response,
-    _ensure_runner_loaded,
-    _prepare_runner_for_model,
-    _resolve_active_runner,
+)
+from .kernel_ingress import (
+    _kernel_error_response,
+    kernel_conversation_turn,
+    kernel_stream_response,
 )
 from .models import (
     RunAgentActionRequest,
@@ -38,11 +64,11 @@ from .models import (
     _runtime_agent_id,
     _split_custom_metadata,
 )
-from .projection import _iter_with_idle_heartbeat
 from .routers import control_router, run_router
 from .streaming import (
     _clear_detached_resume_key,
     _detached_resume_key_from_input,
+    _DetachedSSEStream,
     _reject_if_detached_resume_active,
 )
 
@@ -51,12 +77,15 @@ logger = logging.getLogger(__name__)
 
 @run_router.post("/agentengine/api/v1/RunAgent")
 async def run_agent_action(request: RunAgentActionRequest):
+    executor, launch_context = get_runtime_execution()
+    if kernel_route_active():
+        return await _kernel_run_agent_action(request, launch_context)
     api_format = (request.ApiFormat or "responses").strip().lower()
     run_user_id = _clean_optional_string(request.UserId) or "user"
     account_id = _clean_optional_string(request.AccountId)
     service = deps.resolve_session_service()
     resume_input = (
-        deps.conversation().extract_responses_resume_input(request.ResponsesInput)
+        extract_responses_resume_input(request.ResponsesInput)
         if request.ResponsesInput is not None
         else None
     )
@@ -69,9 +98,9 @@ async def run_agent_action(request: RunAgentActionRequest):
     if resume_input is not None:
         messages = []
     elif request.ResponsesInput is not None and api_format == "responses":
-        messages = deps.conversation().normalize_responses_input(request.ResponsesInput)
+        messages = normalize_responses_input(request.ResponsesInput)
     else:
-        messages = deps.conversation().normalize_kop_messages(request.Messages)
+        messages = normalize_kop_messages(request.Messages)
     request_metadata: dict[str, Any] = (
         {"previous_response_id": request.PreviousResponseId} if request.PreviousResponseId else {}
     )
@@ -81,11 +110,16 @@ async def run_agent_action(request: RunAgentActionRequest):
         request_metadata["responses_conversation"] = True
 
     if request.Background:
+        runtime_preparation = (
+            None
+            if resume_input is not None
+            else await executor.prepare_start(launch_context)
+        )
         invocation_id = request.InvocationId or new_run_id(request.SessionId)
         # 后台 stream 在 detached task 里才被消费（lazy），此时 session 尚未创建。
         # 先 ensure 出 session，才能立刻写 run_status=in_progress（供 SubscribeRunEvents
         # 拉到起始态），并把 resolved session_id 回填给 detached stream 的终态写入与 SubscribeUrl。
-        background_session = await deps.conversation().ensure_conversation_session(
+        background_session = await ensure_conversation_session(
             agent_id=request.AgentId,
             user_id=run_user_id,
             session_id=request.SessionId,
@@ -93,14 +127,14 @@ async def run_agent_action(request: RunAgentActionRequest):
         )
         resolved_background_session_id = background_session.id
         if resume_input is None:
-            await deps.conversation().prime_session_metadata_for_user_turn(
+            await prime_session_metadata_for_user_turn(
                 service=service,
                 session=background_session,
                 messages=messages,
             )
-        await deps.conversation().append_run_status_event(
+        await append_run_status_event(
             session_id=resolved_background_session_id,
-            author=_resolve_active_runner().detection_result.name,
+            author=_runtime_agent_id(launch_context),
             status="in_progress",
             invocation_id=invocation_id,
             session_service_provider=deps.resolve_session_service,
@@ -109,9 +143,10 @@ async def run_agent_action(request: RunAgentActionRequest):
         )
         resume_key = _detached_resume_key_from_input(resolved_background_session_id, resume_input)
         _reject_if_detached_resume_active(resume_key)
-        detached = deps.detached_stream_class()(
-            deps.conversation().stream_responses_conversation_turn(
-                runner=_resolve_active_runner(),
+        detached = _DetachedSSEStream(
+            stream_runtime_responses_conversation_turn(
+                executor=executor,
+                launch_context=launch_context,
                 agent_id=request.AgentId,
                 user_id=run_user_id,
                 messages=messages,
@@ -125,9 +160,9 @@ async def run_agent_action(request: RunAgentActionRequest):
                 resume_input=resume_input,
                 account_id=account_id,
                 invocation_id=invocation_id,
-                prepare_runner=_prepare_runner_for_model,
                 session_service_provider=deps.resolve_session_service,
                 run_mode=RUN_MODE_BACKGROUND,
+                runtime_preparation=runtime_preparation,
             ),
             invocation_id=invocation_id,
             session_id=resolved_background_session_id,
@@ -135,14 +170,15 @@ async def run_agent_action(request: RunAgentActionRequest):
             run_trigger=trigger_from_resume_input(resume_input),
         )
         if invocation_id and resume_key:
+            resolved_resume_key = resume_key
             registry = detached._registry
-            registry.resume_keys_by_invocation[invocation_id] = resume_key
-            registry.active_resume_invocation_by_key[resume_key] = invocation_id
-            detached._task.add_done_callback(
-                lambda _t, inv=invocation_id, rk=resume_key: _clear_detached_resume_key(
-                    registry, inv, rk
-                )
-            )
+            registry.resume_keys_by_invocation[invocation_id] = resolved_resume_key
+            registry.active_resume_invocation_by_key[resolved_resume_key] = invocation_id
+
+            def clear_resume_key(_task: Any) -> None:
+                _clear_detached_resume_key(registry, invocation_id, resolved_resume_key)
+
+            detached._task.add_done_callback(clear_resume_key)
         return _action_response(
             "RunAgent",
             {
@@ -159,12 +195,17 @@ async def run_agent_action(request: RunAgentActionRequest):
         )
 
     if request.Stream:
+        runtime_preparation = (
+            None
+            if resume_input is not None
+            else await executor.prepare_start(launch_context)
+        )
         if api_format == "chat_completions":
-            active_runner = _resolve_active_runner()
             return StreamingResponse(
-                deps.conversation().stream_conversation_turn(
-                    runner=active_runner,
-                    agent_id=_runtime_agent_id(active_runner),
+                stream_runtime_conversation_turn(
+                    executor=executor,
+                    launch_context=launch_context,
+                    agent_id=_runtime_agent_id(launch_context),
                     user_id=run_user_id,
                     messages=messages,
                     session_id=request.SessionId,
@@ -175,17 +216,18 @@ async def run_agent_action(request: RunAgentActionRequest):
                     custom_metadata=custom_metadata,
                     account_id=account_id,
                     invocation_id=request.InvocationId,
-                    prepare_runner=_prepare_runner_for_model,
                     session_service_provider=deps.resolve_session_service,
                     run_mode=RUN_MODE_FOREGROUND,
+                    runtime_preparation=runtime_preparation,
                 ),
                 media_type="text/event-stream",
             )
         resume_key = _detached_resume_key_from_input(request.SessionId, resume_input)
         _reject_if_detached_resume_active(resume_key)
         return deps.detached_streaming_response(
-            deps.conversation().stream_responses_conversation_turn(
-                runner=_resolve_active_runner(),
+            stream_runtime_responses_conversation_turn(
+                executor=executor,
+                launch_context=launch_context,
                 agent_id=request.AgentId,
                 user_id=run_user_id,
                 messages=messages,
@@ -199,9 +241,9 @@ async def run_agent_action(request: RunAgentActionRequest):
                 resume_input=resume_input,
                 account_id=account_id,
                 invocation_id=request.InvocationId,
-                prepare_runner=_prepare_runner_for_model,
                 session_service_provider=deps.resolve_session_service,
                 run_mode=RUN_MODE_FOREGROUND,
+                runtime_preparation=runtime_preparation,
             ),
             invocation_id=request.InvocationId,
             resume_key=resume_key,
@@ -210,8 +252,9 @@ async def run_agent_action(request: RunAgentActionRequest):
         )
 
     responses_response_id = f"resp_{uuid.uuid4().hex}" if api_format != "chat_completions" else None
-    resolved_session_id, result = await deps.conversation().invoke_conversation_once(
-        runner=_resolve_active_runner(),
+    resolved_session_id, result = await invoke_runtime_conversation_once(
+        executor=executor,
+        launch_context=launch_context,
         agent_id=request.AgentId,
         user_id=run_user_id,
         messages=messages,
@@ -225,20 +268,19 @@ async def run_agent_action(request: RunAgentActionRequest):
         response_id=responses_response_id,
         account_id=account_id,
         invocation_id=request.InvocationId,
-        prepare_runner=_prepare_runner_for_model,
         session_service_provider=deps.resolve_session_service,
         run_mode=RUN_MODE_FOREGROUND,
     )
     output_text = result["output_text"]
     if api_format == "chat_completions":
-        payload = deps.conversation().build_chat_completions_payload(
+        payload = build_chat_completions_payload(
             output_text=output_text,
             model=request.Model,
             session_id=resolved_session_id,
             metadata=result.get("metadata"),
         )
     else:
-        payload = deps.conversation().build_responses_payload(
+        payload = build_responses_payload(
             output_text=output_text,
             model=request.Model,
             session_id=resolved_session_id,
@@ -249,472 +291,317 @@ async def run_agent_action(request: RunAgentActionRequest):
     return _action_response("RunAgent", payload)
 
 
+async def _kernel_run_agent_action(request: RunAgentActionRequest, launch_context):
+    """kernel 路径（灰度 opt-in）：RunAgent -> AgentControlCommand -> receipt。
+
+    旧响应 shape 不变；receipt 状态走 RECEIPT_HTTP_STATUS 映射；
+    stream 从 SessionEventSubscription 统一 cursor 读取。
+    """
+    from .kernel_ingress import _kernel_submit
+
+    run_user_id = _clean_optional_string(request.UserId) or "user"
+    session = await ensure_conversation_session(
+        agent_id=request.AgentId,
+        user_id=run_user_id,
+        session_id=request.SessionId,
+        session_service_provider=deps.resolve_session_service,
+    )
+    session_id = session.id
+    idempotency_key = (
+        _clean_optional_string(request.InvocationId)
+        or _clean_optional_string(
+            (request.Metadata or {}).get("IdempotencyKey")
+            if isinstance(request.Metadata, dict)
+            else None
+        )
+        or new_run_id(session_id)
+    )
+    messages = (
+        normalize_responses_input(request.ResponsesInput)
+        if request.ResponsesInput is not None
+        and (request.ApiFormat or "responses").strip().lower() == "responses"
+        else normalize_kop_messages(request.Messages)
+    )
+    # RunAgent 的 Model 覆盖走 runtime_options.model:与 agentengine-server 的
+    # _kernel_runtime_options 投影同构;worker 侧按部署 defaults/白名单校验。
+    runtime_options: dict[str, Any] = {}
+    requested_model = _clean_optional_string(request.Model)
+    if requested_model:
+        runtime_options["model"] = requested_model
+    receipt, trusted = await _kernel_submit(
+        mapper="map_run_request",
+        session_id=session_id,
+        idempotency_key=idempotency_key,
+        content=messages,
+        correlation_ref=request.InvocationId,
+        source_kind="system",
+        runtime_options=runtime_options or None,
+    )
+    if receipt.status not in ("accepted", "duplicate"):
+        return _kernel_error_response(receipt)
+
+    def build_payload(output_text: str):
+        if (request.ApiFormat or "responses").strip().lower() == "chat_completions":
+            return _action_response(
+                "RunAgent",
+                build_chat_completions_payload(
+                    output_text=output_text,
+                    model=request.Model,
+                    session_id=session_id,
+                    metadata=None,
+                ),
+            )
+        return _action_response(
+            "RunAgent",
+            build_responses_payload(
+                output_text=output_text,
+                model=request.Model,
+                session_id=session_id,
+                response_id=f"resp_{uuid.uuid4().hex}",
+                metadata=None,
+                usage=None,
+            ),
+        )
+
+    if request.Stream or request.Background:
+        return kernel_stream_response(
+            receipt=receipt,
+            trusted=trusted,
+            session_id=session_id,
+        )
+    return await kernel_conversation_turn(
+        receipt=receipt,
+        trusted=trusted,
+        session_id=session_id,
+        build_payload=build_payload,
+    )
+
+
 # ============================================================
 # Session Management API (ADK Web Compatible)
 # ============================================================
 
 
-@run_router.post("/run_sse")
-async def run_sse(request: AgentRunRequest):
-    """Unified Streaming Endpoint compatible with ADK Web
+def _adk_sse_event(payload: Mapping[str, Any], *, event: str | None = None) -> str:
+    prefix = f"event: {event}\n" if event else ""
+    return f"{prefix}data: {json.dumps(dict(payload), ensure_ascii=False)}\n\n"
 
-    Respects the `streaming` parameter:
-    - streaming=False: Accumulate full response, send as single event
-    - streaming=True: Stream tokens as they arrive (real-time)
-    """
-    active_runner = _ensure_runner_loaded()
-    _prepare_runner_for_model(active_runner, request.model)
-    use_streaming = request.streaming
-    normalized_message = deps.conversation().normalize_parts_content(
-        request.newMessage.parts if request.newMessage else []
+
+def _adk_usage_metadata(usage: Mapping[str, Any] | None) -> dict[str, int] | None:
+    if not isinstance(usage, Mapping):
+        return None
+    prompt = usage.get("input_tokens", usage.get("prompt_tokens"))
+    candidates = usage.get("output_tokens", usage.get("completion_tokens"))
+    if not isinstance(prompt, int) or not isinstance(candidates, int):
+        return None
+    return {
+        "promptTokenCount": prompt,
+        "candidatesTokenCount": candidates,
+        "totalTokenCount": prompt + candidates,
+    }
+
+
+async def _runtime_run_sse(request: AgentRunRequest) -> StreamingResponse:
+    executor, launch_context = get_runtime_execution()
+    # Validate explicit ownership before StreamingResponse commits HTTP 200.
+    # Also resolve an omitted id exactly once so preparation cannot create a
+    # second, orphaned session after the response generator starts.
+    execution_session = await ensure_conversation_session(
+        agent_id=request.appName,
+        user_id=request.userId,
+        session_id=request.sessionId,
+        session_service_provider=deps.resolve_session_service,
     )
-    user_message = {
+    execution_session_id = execution_session.id
+    normalized = normalize_parts_content(request.newMessage.parts)
+    message = {
         "role": "user",
-        "content": str(normalized_message.get("content") or ""),
-        "display_content": str(normalized_message.get("display_content") or ""),
-        "parts": list(normalized_message.get("parts") or []),
-        "attachments": list(normalized_message.get("attachments") or []),
-        "attachment_results": list(normalized_message.get("attachment_results") or []),
+        "content": str(normalized.get("content") or ""),
+        "display_content": str(normalized.get("display_content") or ""),
+        "parts": list(normalized.get("parts") or []),
+        "attachments": list(normalized.get("attachments") or []),
+        "attachment_results": list(normalized.get("attachment_results") or []),
     }
-
-    model_version = "models/gemini-pro" if "gemini" in request.appName.lower() else "models/unknown"
-    prepared_non_stream: PreparedConversationTurn | None = None
-    if request.sessionId:
-        await deps.conversation().ensure_conversation_session(
-            agent_id=request.appName,
-            user_id=request.userId,
-            session_id=request.sessionId,
-            session_service_provider=deps.resolve_session_service,
-        )
-    if not use_streaming:
-        prepared_non_stream = await deps.conversation().build_run_input(
-            agent_id=request.appName,
-            user_id=request.userId,
-            session_id=request.sessionId,
-            messages=[user_message],
-            state_delta=request.stateDelta or {},
-            invocation_id=request.invocationId,
-            session_service_provider=deps.resolve_session_service,
-        )
-        await deps.conversation().append_run_status_event(
-            session_id=prepared_non_stream.session_id,
-            author=active_runner.detection_result.name,
-            status="in_progress",
-            invocation_id=prepared_non_stream.invocation_id,
-            session_service_provider=deps.resolve_session_service,
-            run_mode=RUN_MODE_FOREGROUND,
-            run_trigger=RUN_TRIGGER_NEW_RUN,
-        )
+    invocation_id = request.invocationId or new_run_id(execution_session_id)
+    author = _runtime_agent_id(launch_context)
 
     async def event_generator():
-        if not use_streaming:
+        if not request.streaming:
             try:
-                assert prepared_non_stream is not None
-                session_id = prepared_non_stream.session_id
-                user_input = prepared_non_stream.user_input
-                attachments = prepared_non_stream.attachments
-                attachment_results = prepared_non_stream.attachment_results
-                current_attachments = prepared_non_stream.current_attachments
-                current_attachment_results = prepared_non_stream.current_attachment_results
-                input_content = prepared_non_stream.input_content
-                input_messages = prepared_non_stream.input_messages
-                user_parts = prepared_non_stream.user_parts
-                history = prepared_non_stream.history
-                invocation_id = prepared_non_stream.invocation_id
-                common_metadata = {
-                    "modelVersion": model_version,
-                    "usageMetadata": {
-                        "promptTokenCount": len(user_input),
-                        "candidatesTokenCount": 0,
-                        "totalTokenCount": len(user_input),
-                    },
-                }
-                input_data = {
-                    "session_id": session_id,
-                    "input": user_input,
-                    "history": history,
-                    "input_content": list(input_content),
-                    "input_messages": list(input_messages),
-                    "input_parts": list(user_parts),
-                    "attachments": attachments,
-                    "attachment_results": attachment_results,
-                    "current_attachments": current_attachments,
-                    "current_attachment_results": current_attachment_results,
-                    "has_current_files": prepared_non_stream.has_current_files,
-                    "model": request.model,
-                }
-                result = await active_runner.invoke(input_data)
-                final_text = result.get("output", "")
-                response_event = {
-                    "id": str(uuid.uuid4()),
-                    "author": active_runner.detection_result.name,
-                    "sessionId": session_id,
-                    "invocationId": invocation_id,
-                    "content": {"role": "model", "parts": [{"text": final_text}]},
-                    "actions": {"finishReason": "STOP"},
-                    "modelVersion": common_metadata["modelVersion"],
-                    "usageMetadata": {
-                        "promptTokenCount": len(user_input),
-                        "candidatesTokenCount": len(final_text),
-                        "totalTokenCount": len(user_input) + len(final_text),
-                    },
-                    "timestamp": int(time.time() * 1000),
-                }
-                yield f"data: {json.dumps(response_event, ensure_ascii=False)}\n\n"
-                if final_text:
-                    await deps.conversation().append_conversation_event(
-                        session_id=session_id,
-                        author=active_runner.detection_result.name,
-                        role="model",
-                        text=final_text,
-                        invocation_id=invocation_id,
-                        event_type="assistant_message",
-                        session_service_provider=deps.resolve_session_service,
-                    )
-                await deps.conversation().append_run_status_event(
-                    session_id=session_id,
-                    author=active_runner.detection_result.name,
-                    status="completed",
-                    invocation_id=invocation_id,
-                    session_service_provider=deps.resolve_session_service,
-                    run_mode=RUN_MODE_FOREGROUND,
-                    run_trigger=RUN_TRIGGER_NEW_RUN,
-                )
-
-            except Exception:
-                logger.exception("Error in invoke")
-                public_error = "The agent run failed. See server logs for details."
-                await deps.conversation().append_run_status_event(
-                    session_id=session_id,
-                    author=active_runner.detection_result.name,
-                    status="failed",
+                session_id, result = await invoke_runtime_conversation_once(
+                    executor=executor,
+                    launch_context=launch_context,
+                    agent_id=request.appName,
+                    user_id=request.userId,
+                    messages=[message],
+                    session_id=execution_session_id,
+                    model=request.model,
+                    state_delta=request.stateDelta or {},
                     invocation_id=invocation_id,
-                    detail=public_error,
                     session_service_provider=deps.resolve_session_service,
                     run_mode=RUN_MODE_FOREGROUND,
-                    run_trigger=RUN_TRIGGER_NEW_RUN,
                 )
-                error_event = {
+                output_text = str(result.get("output_text") or "")
+                payload: dict[str, Any] = {
                     "id": str(uuid.uuid4()),
+                    "author": author,
                     "sessionId": session_id,
                     "invocationId": invocation_id,
-                    "error": "agent_run_failed",
-                    "errorMessage": public_error,
+                    "content": {"role": "model", "parts": [{"text": output_text}]},
+                    "actions": {"finishReason": "STOP"},
+                    "modelVersion": request.model or "models/unknown",
                     "timestamp": int(time.time() * 1000),
                 }
-                yield f"data: {json.dumps(error_event, ensure_ascii=False)}\n\n"
-        else:
-            try:
-                compaction_preview = await deps.conversation().preview_auto_compaction(
-                    agent_id=request.appName,
-                    user_id=request.userId,
-                    session_id=request.sessionId,
-                    messages=[user_message],
-                    session_service_provider=deps.resolve_session_service,
+                usage_metadata = _adk_usage_metadata(result.get("usage"))
+                if usage_metadata is not None:
+                    payload["usageMetadata"] = usage_metadata
+                yield _adk_sse_event(payload)
+            except Exception:
+                logger.exception("Error in RuntimeAdapter invoke")
+                yield _adk_sse_event(
+                    {
+                        "id": str(uuid.uuid4()),
+                        "sessionId": execution_session_id,
+                        "invocationId": invocation_id,
+                        "error": "agent_run_failed",
+                        "errorMessage": "The agent run failed. See server logs for details.",
+                        "timestamp": int(time.time() * 1000),
+                    }
                 )
-                if compaction_preview.should_compact:
-                    yield deps.conversation().build_compaction_sse_event(
-                        phase="start",
-                        trigger="auto",
-                        total_chars=compaction_preview.total_chars,
-                        group_count=compaction_preview.group_count,
-                    )
+            return
 
-                prepared = await deps.conversation().build_run_input(
-                    agent_id=request.appName,
-                    user_id=request.userId,
-                    session_id=request.sessionId,
-                    messages=[user_message],
-                    state_delta=request.stateDelta or {},
-                    invocation_id=request.invocationId,
-                    session_service_provider=deps.resolve_session_service,
-                )
-                if prepared.compaction_triggered:
-                    yield deps.conversation().build_compaction_sse_event(
-                        phase="done",
-                        trigger=str(prepared.compaction_trigger or "auto"),
-                        compacted_until_seq_id=prepared.compacted_until_seq_id,
-                        total_chars=(
-                            compaction_preview.total_chars
-                            if compaction_preview.should_compact
-                            else None
-                        ),
-                        group_count=(
-                            compaction_preview.group_count
-                            if compaction_preview.should_compact
-                            else None
-                        ),
+        session_id = execution_session_id
+        visible_text = ""
+        try:
+            async for event in iter_runtime_conversation_semantic_events(
+                executor=executor,
+                launch_context=launch_context,
+                agent_id=request.appName,
+                user_id=request.userId,
+                messages=[message],
+                session_id=execution_session_id,
+                model=request.model,
+                state_delta=request.stateDelta or {},
+                invocation_id=invocation_id,
+                session_service_provider=deps.resolve_session_service,
+                run_mode=RUN_MODE_FOREGROUND,
+            ):
+                event_type = event.get("type")
+                session_id = str(event.get("session_id") or session_id)
+                if event_type == "thinking":
+                    yield _adk_sse_event(
+                        {"delta": str(event.get("delta") or "")},
+                        event="response.reasoning.delta",
                     )
-
-                session_id = prepared.session_id
-                user_input = prepared.user_input
-                attachments = prepared.attachments
-                attachment_results = prepared.attachment_results
-                current_attachments = prepared.current_attachments
-                current_attachment_results = prepared.current_attachment_results
-                input_content = prepared.input_content
-                input_messages = prepared.input_messages
-                user_parts = prepared.user_parts
-                history = prepared.history
-                invocation_id = prepared.invocation_id
-                common_metadata = {
-                    "modelVersion": model_version,
-                    "usageMetadata": {
-                        "promptTokenCount": len(user_input),
-                        "candidatesTokenCount": 0,
-                        "totalTokenCount": len(user_input),
-                    },
-                }
-                await deps.conversation().append_run_status_event(
-                    session_id=session_id,
-                    author=active_runner.detection_result.name,
-                    status="in_progress",
-                    invocation_id=invocation_id,
-                    session_service_provider=deps.resolve_session_service,
-                    run_mode=RUN_MODE_FOREGROUND,
-                    run_trigger=RUN_TRIGGER_NEW_RUN,
-                )
-
-                client_visible_text = ""
-                authoritative_text = ""
-                responses_output: list[Any] = []
-                responses_response_id: str | None = None
-                stream_iter = active_runner.stream(
-                    {
-                        "session_id": session_id,
-                        "input": user_input,
-                        "history": history,
-                        "input_content": list(input_content),
-                        "input_messages": list(input_messages),
-                        "input_parts": list(user_parts),
-                        "attachments": attachments,
-                        "attachment_results": attachment_results,
-                        "current_attachments": current_attachments,
-                        "current_attachment_results": current_attachment_results,
-                        "has_current_files": prepared.has_current_files,
-                        "model": request.model,
+                elif event_type == "compaction":
+                    phase = str(event.get("phase") or "done")
+                    yield _adk_sse_event(
+                        {
+                            key: value
+                            for key, value in event.items()
+                            if key not in {"type", "phase"} and value is not None
+                        },
+                        event=f"response.compaction.{phase}",
+                    )
+                elif event_type == "text":
+                    delta = str(event.get("delta") or "")
+                    replace = bool(event.get("replace"))
+                    visible_text = delta if replace else visible_text + delta
+                    text_payload: dict[str, Any] = {
+                        "id": str(uuid.uuid4()),
+                        "author": author,
+                        "sessionId": session_id,
+                        "invocationId": invocation_id,
+                        "content": {"role": "model", "parts": [{"text": delta}]},
+                        "timestamp": int(time.time() * 1000),
                     }
-                )
-                async for kind, chunk in _iter_with_idle_heartbeat(stream_iter):
-                    if kind == "heartbeat":
-                        yield ": ping\n\n"
-                        continue
-                    event_id = str(uuid.uuid4())
-                    if chunk.get("type") == "responses_output":
-                        raw_output = chunk.get("output")
-                        responses_output = raw_output if isinstance(raw_output, list) else []
-                        raw_response_id = chunk.get("response_id")
-                        responses_response_id = (
-                            str(raw_response_id) if raw_response_id else responses_response_id
+                    if replace:
+                        # A replacement snapshot is authoritative final output,
+                        # not another partial token. Keep the replacement hint
+                        # so clients can discard previously rendered deltas.
+                        text_payload.update(
+                            {
+                                "replace": True,
+                                "actions": {"finishReason": "STOP"},
+                                "modelVersion": request.model or "models/unknown",
+                            }
                         )
-                        continue
-                    if chunk.get("type") == "thinking":
-                        delta = str(chunk.get("delta", ""))
-                        if delta:
-                            await deps.conversation().append_reasoning_event(
-                                session_id=session_id,
-                                author=active_runner.detection_result.name,
-                                text=delta,
-                                invocation_id=invocation_id,
-                                session_service_provider=deps.resolve_session_service,
-                            )
-                            yield (
-                                "event: response.reasoning.delta\n"
-                                f"data: {json.dumps({'delta': delta}, ensure_ascii=False)}\n\n"
-                            )
-                        continue
-                    if chunk.get("type") == "text":
-                        delta_text = chunk.get("delta", "")
-                        client_visible_text += delta_text
-                        authoritative_text = client_visible_text
-                        response_event = {
-                            "id": event_id,
-                            "author": chunk.get("node", active_runner.detection_result.name),
-                            "sessionId": session_id,
-                            "invocationId": invocation_id,
-                            "content": {"role": "model", "parts": [{"text": delta_text}]},
-                            "partial": True,
-                            "timestamp": int(time.time() * 1000),
-                        }
-                        yield f"data: {json.dumps(response_event, ensure_ascii=False)}\n\n"
-                        continue
-                    if chunk.get("type") == "tool_call":
-                        yield (
-                            "event: response.tool_call\n"
-                            "data: "
-                            + json.dumps(
-                                {
-                                    "name": chunk.get("tool_name"),
-                                    "args": chunk.get("tool_args", {}),
+                    else:
+                        text_payload.update({"partial": True, "replace": False})
+                    yield _adk_sse_event(
+                        text_payload
+                    )
+                elif event_type == "tool_call":
+                    yield _adk_sse_event(
+                        {"name": event.get("name"), "args": event.get("args") or {}},
+                        event="response.tool_call",
+                    )
+                elif event_type == "tool_result":
+                    yield _adk_sse_event(
+                        {"name": event.get("name"), "output": event.get("output")},
+                        event="response.tool_result",
+                    )
+                elif event_type == "interrupt":
+                    yield _adk_sse_event(
+                        {"interrupt_info": event.get("interrupt_info")},
+                        event="response.approval_request",
+                    )
+                elif event_type == "completed":
+                    final_text = str(event.get("output_text") or visible_text)
+                    if final_text != visible_text:
+                        yield _adk_sse_event(
+                            {
+                                "id": str(uuid.uuid4()),
+                                "author": author,
+                                "sessionId": session_id,
+                                "invocationId": invocation_id,
+                                "content": {
+                                    "role": "model",
+                                    "parts": [{"text": final_text}],
                                 },
-                                ensure_ascii=False,
-                            )
-                            + "\n\n"
+                                "actions": {"finishReason": "STOP"},
+                                "modelVersion": request.model or "models/unknown",
+                                "timestamp": int(time.time() * 1000),
+                            }
                         )
-                        tool_event = {
-                            "id": event_id,
-                            "author": chunk.get("node", "tool"),
+                elif event_type == "error":
+                    yield _adk_sse_event(
+                        {
+                            "id": str(uuid.uuid4()),
                             "sessionId": session_id,
                             "invocationId": invocation_id,
-                            "content": {
-                                "role": "model",
-                                "parts": [
-                                    {
-                                        "functionCall": {
-                                            "name": chunk.get("tool_name", "unknown"),
-                                            "args": chunk.get("tool_args", {}),
-                                        }
-                                    }
-                                ],
-                            },
-                            "actions": {
-                                "finishReason": "STOP",
-                                "stateDelta": {},
-                            },
-                            "modelVersion": common_metadata["modelVersion"],
+                            "error": "agent_run_failed",
+                            "errorMessage": str(event.get("message") or "Agent run failed"),
                             "timestamp": int(time.time() * 1000),
                         }
-                        yield f"data: {json.dumps(tool_event, ensure_ascii=False)}\n\n"
-                        await deps.conversation().append_conversation_event(
-                            session_id=session_id,
-                            author=chunk.get("node", "tool"),
-                            role="model",
-                            text="",
-                            invocation_id=invocation_id,
-                            event_type="tool_call",
-                            session_service_provider=deps.resolve_session_service,
-                            metadata={
-                                "tool_name": chunk.get("tool_name", "unknown"),
-                                "tool_args": chunk.get("tool_args", {}),
-                            },
-                        )
-                        continue
-                    if chunk.get("type") == "tool_result":
-                        await deps.conversation().append_conversation_event(
-                            session_id=session_id,
-                            author=active_runner.detection_result.name,
-                            role="user",
-                            text=str(chunk.get("tool_output", "")),
-                            invocation_id=invocation_id,
-                            event_type="tool_result",
-                            session_service_provider=deps.resolve_session_service,
-                            metadata={
-                                "tool_name": chunk.get("tool_name"),
-                                "tool_output": chunk.get("tool_output", {}),
-                            },
-                        )
-                        yield (
-                            "event: response.tool_result\n"
-                            "data: "
-                            + json.dumps(
-                                {
-                                    "name": chunk.get("tool_name"),
-                                    "output": chunk.get("tool_output", {}),
-                                },
-                                ensure_ascii=False,
-                            )
-                            + "\n\n"
-                        )
-                        continue
-                    if chunk.get("type") == "interrupt":
-                        await deps.conversation().append_conversation_event(
-                            session_id=session_id,
-                            author=active_runner.detection_result.name,
-                            role="model",
-                            text="approval requested",
-                            invocation_id=invocation_id,
-                            event_type="approval_request",
-                            session_service_provider=deps.resolve_session_service,
-                            metadata={"interrupt_info": chunk.get("interrupt_info")},
-                        )
-                        yield (
-                            "event: response.approval_request\n"
-                            "data: "
-                            + json.dumps(
-                                {"interrupt_info": chunk.get("interrupt_info")},
-                                ensure_ascii=False,
-                            )
-                            + "\n\n"
-                        )
-                        continue
-                    if chunk.get("type") == "final":
-                        final_text = chunk.get("output", "")
-                        if not final_text:
-                            continue
-                        authoritative_text = final_text
-                        if final_text != client_visible_text:
-                            final_event = {
-                                "id": event_id,
-                                "author": active_runner.detection_result.name,
-                                "sessionId": session_id,
-                                "invocationId": invocation_id,
-                                "content": {"role": "model", "parts": [{"text": final_text}]},
-                                "actions": {"finishReason": "STOP"},
-                                "modelVersion": common_metadata["modelVersion"],
-                                "usageMetadata": {
-                                    "promptTokenCount": len(user_input),
-                                    "candidatesTokenCount": len(final_text),
-                                    "totalTokenCount": len(user_input) + len(final_text),
-                                },
-                                "timestamp": int(time.time() * 1000),
-                            }
-                            yield f"data: {json.dumps(final_event, ensure_ascii=False)}\n\n"
-                            client_visible_text = final_text
-
-                if authoritative_text:
-                    await deps.conversation().append_conversation_event(
-                        session_id=session_id,
-                        author=active_runner.detection_result.name,
-                        role="model",
-                        text=authoritative_text,
-                        invocation_id=invocation_id,
-                        event_type="assistant_message",
-                        metadata={
-                            **({"responses_output": responses_output} if responses_output else {}),
-                            **(
-                                {"response_id": responses_response_id}
-                                if responses_response_id
-                                else {}
-                            ),
-                        },
-                        session_service_provider=deps.resolve_session_service,
                     )
-                await deps.conversation().append_run_status_event(
-                    session_id=session_id,
-                    author=active_runner.detection_result.name,
-                    status="completed",
-                    invocation_id=invocation_id,
-                    session_service_provider=deps.resolve_session_service,
-                    run_mode=RUN_MODE_FOREGROUND,
-                    run_trigger=RUN_TRIGGER_NEW_RUN,
-                )
-
-            except Exception:
-                logger.exception("Error in stream")
-                public_error = "The agent run failed. See server logs for details."
-                await deps.conversation().append_run_status_event(
-                    session_id=session_id,
-                    author=active_runner.detection_result.name,
-                    status="failed",
-                    invocation_id=invocation_id,
-                    detail=public_error,
-                    session_service_provider=deps.resolve_session_service,
-                    run_mode=RUN_MODE_FOREGROUND,
-                    run_trigger=RUN_TRIGGER_NEW_RUN,
-                )
-                error_event = {
+        except Exception:
+            logger.exception("Error in RuntimeAdapter stream")
+            yield _adk_sse_event(
+                {
                     "id": str(uuid.uuid4()),
                     "sessionId": session_id,
                     "invocationId": invocation_id,
                     "error": "agent_run_failed",
-                    "errorMessage": public_error,
+                    "errorMessage": "The agent run failed. See server logs for details.",
                     "timestamp": int(time.time() * 1000),
                 }
-                yield f"data: {json.dumps(error_event, ensure_ascii=False)}\n\n"
+            )
 
     return StreamingResponse(event_generator(), media_type="text/event-stream")
 
 
+@run_router.post("/run_sse")
+async def run_sse(request: AgentRunRequest):
+    """Unified Streaming Endpoint compatible with ADK Web
+
+    Respects the `streaming` parameter:
+    - streaming=False: Accumulate full response, send as single event
+    - streaming=True: Stream tokens as they arrive (real-time)
+    """
+    return await _runtime_run_sse(request)
+
+
 # ============================================================
 # Trace / Debug API (ADK Web Compatible)
 # ============================================================