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

ksadk/studio/run_service.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import asyncio
+import copy
 import hashlib
 import json
 import logging
@@ -14,6 +15,8 @@ from pathlib import Path
 from typing import Any
 from uuid import uuid4
 
+from jsonschema import Draft202012Validator
+
 from ksadk.agui.a2ui_projection import project_a2ui_operations
 from ksadk.conversations.projector import (
     project_conversation_item,
@@ -60,14 +63,17 @@ from ksadk.runtime import (
     RuntimeLaunchContext,
     StartRequest,
 )
+from ksadk.runtime.executor import RuntimeStartPreparation
 from ksadk.sessions.base import BaseSessionService
 from ksadk.sessions.local_service import LocalSessionService
 from ksadk.studio.contracts import RunEvent, RunRecord, RunStatus, Usage
 from ksadk.studio.errors import StudioError
 from ksadk.studio.event_store import RunEventStore
+from ksadk.studio.run_activity import project_run_activities
 from ksadk.studio.workspace import Workspace
 
 _CANCEL_TIMEOUT_SECONDS = 2.0
+_INTERACTION_SUBMIT_TIMEOUT_SECONDS = 10.0
 
 
 logger = logging.getLogger(__name__)
@@ -86,6 +92,129 @@ class StudioRunSpec:
     plugin_bundle_root: Path | None = None
 
 
+class _ProjectedRunEventWriter:
+    """Batch high-frequency text deltas before rewriting a Run JSON file.
+
+    Canonical RuntimeEvents are already durable in the session store.  The
+    RunEvent JSON is a presentation projection, so writing and retaining one
+    copy of the full projection envelope per token is unnecessary and becomes
+    quadratic as the response grows.  A short batching window keeps live chat
+    responsive and coalesces adjacent chunks for the same projected item.
+    """
+
+    _STREAM_TYPES = frozenset({"message.delta", "thinking.delta"})
+
+    def __init__(
+        self,
+        event_store: RunEventStore,
+        run_id: str,
+        on_event: Callable[[RunEvent], None] | None,
+        *,
+        flush_interval: float = 0.5,
+    ) -> None:
+        self._event_store = event_store
+        self._run_id = run_id
+        self._on_event = on_event
+        self._flush_interval = flush_interval
+        self._pending: list[tuple[str, dict[str, Any]]] = []
+        # Publish the first chunk immediately so the UI can enter streaming
+        # state without waiting for the batching window. Subsequent chunks are
+        # coalesced into short durable writes.
+        self._last_flush = 0.0
+        self._flush_handle: asyncio.TimerHandle | None = None
+
+    def append(self, event_type: str, data: dict[str, Any]) -> RunEvent | None:
+        if event_type in self._STREAM_TYPES:
+            self._pending.append((event_type, data))
+            elapsed = time.monotonic() - self._last_flush
+            if elapsed < self._flush_interval:
+                if self._flush_handle is None:
+                    self._flush_handle = asyncio.get_running_loop().call_later(
+                        self._flush_interval - elapsed, self.flush
+                    )
+                return None
+            return self.flush()[-1]
+        self.flush()
+        stored = self._event_store.append(self._run_id, event_type, data)
+        self._notify((stored,))
+        return stored
+
+    def flush(self) -> list[RunEvent]:
+        if self._flush_handle is not None:
+            self._flush_handle.cancel()
+            self._flush_handle = None
+        if not self._pending:
+            return []
+        pending, self._pending = self._pending, []
+        stored = self._event_store.append_many(
+            self._run_id,
+            self._coalesce_stream_entries(pending),
+        )
+        self._last_flush = time.monotonic()
+        self._notify(stored)
+        return stored
+
+    @staticmethod
+    def _coalesce_stream_entries(
+        entries: list[tuple[str, dict[str, Any]]],
+    ) -> list[tuple[str, dict[str, Any]]]:
+        """Collapse adjacent chunks without changing the rendered transcript."""
+
+        coalesced: list[tuple[str, dict[str, Any]]] = []
+        for event_type, data in entries:
+            if not coalesced:
+                coalesced.append((event_type, copy.deepcopy(data)))
+                continue
+            previous_type, previous = coalesced[-1]
+            if not _same_projected_stream(previous_type, previous, event_type, data):
+                coalesced.append((event_type, copy.deepcopy(data)))
+                continue
+
+            operation = str(data.get("operation") or "append")
+            if operation == "append":
+                merged_text = str(previous.get("text") or "") + str(data.get("text") or "")
+                merged = copy.deepcopy(data)
+                _set_projected_stream_text(merged, merged_text)
+                coalesced[-1] = (event_type, merged)
+            else:
+                coalesced[-1] = (event_type, copy.deepcopy(data))
+        return coalesced
+
+    def _notify(self, events: tuple[RunEvent, ...] | list[RunEvent]) -> None:
+        if self._on_event is None:
+            return
+        for event in events:
+            self._on_event(event)
+
+
+def _same_projected_stream(
+    previous_type: str,
+    previous: dict[str, Any],
+    event_type: str,
+    data: dict[str, Any],
+) -> bool:
+    return (
+        previous_type == event_type
+        and previous.get("itemId") == data.get("itemId")
+        and previous.get("partId") == data.get("partId")
+        and previous.get("operation") == data.get("operation")
+    )
+
+
+def _set_projected_stream_text(data: dict[str, Any], text: str) -> None:
+    data["text"] = text
+    conversation_item = data.get("conversationItem")
+    if isinstance(conversation_item, dict):
+        payload = conversation_item.get("payload")
+        if isinstance(payload, dict):
+            payload["text"] = text
+    runtime_event = data.get("runtimeEvent")
+    if isinstance(runtime_event, dict):
+        update = runtime_event.get("update")
+        if isinstance(update, dict):
+            update["text"] = text
+
+
 class StudioRunService:
     """Persist Studio state without selecting or wrapping a RuntimeAdapter."""
 
@@ -107,29 +236,77 @@ class StudioRunService:
         )
         self.runtime_events = runtime_events or RuntimeEventStore(self.session_service)
         self.plugin_runtime = plugin_runtime
+        self.schedule_assistant: Any | None = None
         self._active_handles: dict[str, Any] = {}
+        self._active_sessions: set[tuple[str, str]] = set()
         self._cancel_flags: dict[str, bool] = {}
         self._control_queues: dict[
             str,
             asyncio.Queue[tuple[str, ResumePayload | None, asyncio.Future[None] | None]],
         ] = {}
         self._waiting_modes: dict[str, str] = {}
+        self._submitted_interactions: dict[str, set[str]] = {}
         # Interaction resolution appends to one run-level event file.  Serialise
         # every decision for that run, not only identical interaction ids, so
         # two concurrently visible cards cannot overwrite each other's receipt.
         self._interaction_locks: dict[str, asyncio.Lock] = {}
+        self._recovery_tasks: set[asyncio.Task] = set()
+        self._detaching_recoveries = False
+
+    def has_active_runs(self) -> bool:
+        return bool(self._active_sessions or self._active_handles)
+
+    def is_run_executing(self, run_id: str) -> bool:
+        """该 run 是否仍在本进程内实际执行（内存态判定）。
 
-    async def recover_interrupted(self) -> None:
+        磁盘 record 停在 RUNNING 的 run 若不在这里，说明是进程崩溃/重启
+        遗留的僵尸状态，允许删除会话时将其收尾为 canceled。
+        """
+        return run_id in self._active_handles or run_id in self._active_sessions
+
+    async def reap_stale_running_run(self, run_id: str) -> bool:
+        """把不在执行的僵尸 RUNNING run 收尾为 canceled（幂等）。"""
+        from ksadk.events.canonical import RunCanceled
+
+        record = self.event_store.get(run_id)
+        if record.status != RunStatus.RUNNING or self.is_run_executing(run_id):
+            return False
+        record.status = RunStatus.CANCELLED
+        record.error = {"code": "RUN_CANCELLED", "message": "会话删除时回收未完成的运行"}
+        record.completed_at = datetime.now(timezone.utc)
+        self.event_store.save(record)
+        await self.runtime_events.append_one(
+            record.session_id,
+            RunCanceled(
+                schema_version=2,
+                event_id=f"evt_reap_{uuid4().hex}",
+                seq=len(self.event_store.events(run_id)) + 1,
+                timestamp=time.time(),
+                run_id=run_id,
+                scope_id=run_id,
+                source=SourceRef(framework="ksadk", metadata={"reason": "session_deleted"}),
+                status="canceled",
+                reason="session deleted",
+            ),
+        )
+        return True
+
+    async def recover_interrupted(self, resolve_spec=None) -> None:
         """Settle local runs left active across a Studio restart.
 
-        An in-process handle cannot be resumed safely.  Keep its durable event
-        history and record an explicit interruption; lease-backed hosted
-        recovery remains owned by the Kernel composition root.
+        Reattach approval-paused providers only when their pinned Build and
+        durable-restore capability can be verified. Other in-process runs are
+        explicitly interrupted; active execution takeover remains Kernel-owned.
         """
         active = {RunStatus.RUNNING, RunStatus.WAITING_INPUT}
         for record in self.event_store.list_runs():
             if record.status not in active:
                 continue
+            if record.status == RunStatus.WAITING_INPUT and resolve_spec is not None:
+                from ksadk.studio.provider_recovery import restore_waiting_provider_run
+
+                if await restore_waiting_provider_run(self, record, resolve_spec):
+                    continue
             record.status = RunStatus.INTERRUPTED
             record.completed_at = datetime.now(timezone.utc)
             record.error = {
@@ -142,6 +319,7 @@ class StudioRunService:
                 "run.interrupted",
                 {"reason": "local_studio_restarted", "recoverable": False},
             )
+            self._expire_unresolved_interactions(record)
 
     async def events(self, run_id: str, *, after: int = 0) -> list[RunEvent]:
         """Read the durable Studio event timeline for API/SSE replay."""
@@ -155,6 +333,38 @@ class StudioRunService:
         runtime_input: Any = None,
         session_id: str | None = None,
         on_event: Callable[[RunEvent], None] | None = None,
+    ) -> RunRecord:
+        session = session_id or f"ses_{uuid4().hex}"
+        key = (spec.agent_id, session)
+        # Claim before the first await, including preparation and plugin runs.
+        # A second turn must never attach another adapter to the live thread.
+        if key in self._active_sessions:
+            raise StudioError(
+                "SESSION_RUN_ACTIVE",
+                "上一轮仍在运行或等待回答，请先完成回答或停止运行。",
+                status_code=409,
+                details={"sessionId": session},
+            )
+        self._active_sessions.add(key)
+        try:
+            return await self._run_owned(
+                spec,
+                user_input,
+                runtime_input=runtime_input,
+                session_id=session,
+                on_event=on_event,
+            )
+        finally:
+            self._active_sessions.discard(key)
+
+    async def _run_owned(
+        self,
+        spec: StudioRunSpec,
+        user_input: str,
+        *,
+        runtime_input: Any,
+        session_id: str,
+        on_event: Callable[[RunEvent], None] | None,
     ) -> RunRecord:
         run_id = f"run_{uuid4().hex}"
         session = session_id or f"ses_{uuid4().hex}"
@@ -193,7 +403,27 @@ class StudioRunService:
         if on_event is not None:
             on_event(created)
 
-        kernel_runtime = self._kernel_runtime_for_spec(spec)
+        if self.schedule_assistant is not None and (
+            self.schedule_assistant.matches(user_input)
+            or self.schedule_assistant.matches_followup(spec.agent_id, session, user_input)
+        ):
+            handled = await self._schedule_run(record, user_input, on_event=on_event)
+            if handled is not None:
+                return handled
+
+        provider_runtime_adapter = (
+            spec.plugin_bundle_root is not None
+            and (
+                runtime_type == "codex"
+                or bool(spec.request_config.get("provider_runtime_adapter"))
+            )
+        )
+        # A process-global Codex Kernel can share Agent/cwd with this Build
+        # while owning a legacy direct factory. New Builds must retain their
+        # exact Provider activation, including when that global Kernel exists.
+        kernel_runtime = (
+            None if provider_runtime_adapter else self._kernel_runtime_for_spec(spec)
+        )
         if kernel_runtime is not None:
             return await self._kernel_run(
                 spec,
@@ -202,7 +432,7 @@ class StudioRunService:
                 on_event=on_event,
                 kernel_runtime=kernel_runtime,
             )
-        if spec.plugin_bundle_root is not None:
+        if spec.plugin_bundle_root is not None and not provider_runtime_adapter:
             return await self._plugin_run(
                 spec,
                 user_input,
@@ -210,12 +440,28 @@ class StudioRunService:
                 on_event=on_event,
             )
 
+        return await self._execute_runtime_record(
+            spec, user_input, record=record, runtime_input=runtime_input,
+            on_event=on_event, prepared_turn=prepared_turn,
+            provider_runtime_adapter=provider_runtime_adapter,
+        )
+
+    async def _execute_runtime_record(
+        self, spec, user_input, *, record, runtime_input=None, on_event=None,
+        prepared_turn=None, provider_runtime_adapter=False, restored_handle=None,
+    ) -> RunRecord:
+        run_id, session = record.id, record.session_id
+        runtime_type = record.runtime_type
         started = time.monotonic()
-        record.status = RunStatus.RUNNING
-        record.started_at = datetime.now(timezone.utc)
+        if restored_handle is None:
+            record.status = RunStatus.RUNNING
+            record.started_at = datetime.now(timezone.utc)
         self.event_store.save(record)
+        projected_writer = _ProjectedRunEventWriter(self.event_store, run_id, on_event)
 
-        async def persist(runtime_event: RuntimeEvent) -> RunEvent:
+        async def persist(runtime_event: RuntimeEvent) -> RunEvent | None:
+            if _is_private_harness_delta(runtime_event):
+                return None
             persisted = await self.runtime_events.append_one(record.session_id, runtime_event)
             event_type, data = project_runtime_event(
                 persisted,
@@ -229,10 +475,7 @@ class StudioRunService:
                     item_payload = conversation_item.get("payload")
                     if isinstance(item_payload, dict):
                         item_payload["revision"] = 1
-            stored = self.event_store.append(record.id, event_type, data)
-            if on_event is not None:
-                on_event(stored)
-            return stored
+            return projected_writer.append(event_type, data)
 
         handle = None
         completed_text_by_item: dict[tuple[str, str], str] = {}
@@ -269,17 +512,60 @@ class StudioRunService:
                 metadata={
                     "invocation_id": run_id,
                     CONVERSATION_PREPROCESSING_METADATA_KEY: conversation_request,
-                    **self._native_session_metadata(spec.agent_id, session, runtime_type),
+                    **self._native_session_metadata(
+                        spec.agent_id,
+                        session,
+                        str(
+                            spec.request_config.get("provider_runtime_type")
+                            or runtime_type
+                        ),
+                        spec.build_id,
+                    ),
                 },
             )
-            handle = await self.executor.start(spec.launch_context, request)
+            preparation = None
+            if provider_runtime_adapter:
+                if self.plugin_runtime is None:
+                    raise StudioError(
+                        "PLUGIN_RUNTIME_UNAVAILABLE", "Codex Provider Runtime 不可用",
+                        status_code=503,
+                    )
+                adapter = self.plugin_runtime.kernel_adapter_provider(spec)()
+                preparation = RuntimeStartPreparation(context=spec.launch_context, adapter=adapter)
+            handle = restored_handle or await self.executor.start(
+                spec.launch_context, request, preparation=preparation,
+            )
             record.runtime_handle = handle.model_dump(mode="json")
             self.event_store.save(record)
             self._active_handles[run_id] = handle
             while True:
                 terminal_seen = False
-                should_resume = False
+                should_resume = restored_handle is not None
+                if restored_handle is not None:
+                    self._waiting_modes[run_id] = "resume"
+                    restored_handle = None
                 async for event in self.executor.stream(handle):
+                    if (
+                        isinstance(event, RunInterrupted)
+                        and event.interaction_id
+                        and record.status == RunStatus.WAITING_INPUT
+                        and event.source.framework == "codex"
+                    ):
+                        # Codex emits this companion event immediately after a
+                        # live JSON-RPC approval request. The native turn stays
+                        # attached and must be released through submit; trying
+                        # to resume it deadlocks that request and later breaks
+                        # the app-server pipe.
+                        self._waiting_modes[run_id] = "live"
+                        continue
+                    if isinstance(event, InteractionResolved) and event.source.framework == "codex":
+                        submitted = self._submitted_interactions.get(run_id, set())
+                        provider_call_id = str(getattr(event.response, "call_id", None) or "")
+                        if event.interaction_id in submitted or provider_call_id in submitted:
+                            # submit_interaction atomically persists the public
+                            # terminal fact and receipt. Ignore the provider's
+                            # echo so replay never shows the approval twice.
+                            continue
                     await persist(event)
                     if self._cancel_flags.get(run_id):
                         raise asyncio.CancelledError()
@@ -288,9 +574,7 @@ class StudioRunService:
                     elif (
                         isinstance(event, ItemUpdated)
                         and event.item_kind == "message"
-                        and item_phases.get(
-                            (event.scope_id, event.item_id), "final_answer"
-                        )
+                        and item_phases.get((event.scope_id, event.item_id), "final_answer")
                         == "final_answer"
                     ):
                         text = event.update.text if isinstance(event.update, TextContent) else ""
@@ -304,9 +588,7 @@ class StudioRunService:
                     elif (
                         isinstance(event, ItemCompleted)
                         and event.item_kind == "message"
-                        and item_phases.get(
-                            (event.scope_id, event.item_id), "final_answer"
-                        )
+                        and item_phases.get((event.scope_id, event.item_id), "final_answer")
                         == "final_answer"
                     ):
                         completed_text_by_item[(event.scope_id, event.item_id)] = "".join(
@@ -428,6 +710,8 @@ class StudioRunService:
                 fallback_parts = [part for part in streamed_text_by_item.values() if part]
                 record.output = "\n\n".join(completed_parts or fallback_parts)
         except asyncio.CancelledError:
+            if self._detaching_recoveries and record.status == RunStatus.WAITING_INPUT:
+                raise
             cancel_result = "task_cancelled"
             if handle is not None and self.executor.is_attached(handle):
                 try:
@@ -481,6 +765,7 @@ class StudioRunService:
             )
             await persist(failure)
         finally:
+            projected_writer.flush()
             if handle is not None and self.executor.is_attached(handle):
                 try:
                     await asyncio.shield(self.executor.close(handle))
@@ -492,7 +777,13 @@ class StudioRunService:
             self._cancel_flags.pop(run_id, None)
             self._control_queues.pop(run_id, None)
             self._waiting_modes.pop(run_id, None)
-            record.completed_at = datetime.now(timezone.utc)
+            self._submitted_interactions.pop(run_id, None)
+            preserve_waiting = (
+                self._detaching_recoveries and record.status == RunStatus.WAITING_INPUT
+            )
+            if not preserve_waiting:
+                record.completed_at = datetime.now(timezone.utc)
+                self._expire_unresolved_interactions(record, on_event=on_event)
             if runtime_duration_ms is not None:
                 record.duration_ms = runtime_duration_ms
                 record.duration_source = "runtime"
@@ -503,6 +794,179 @@ class StudioRunService:
             await self._sync_trace(record)
         return record
 
+    async def _schedule_run(
+        self,
+        record: RunRecord,
+        user_input: str,
+        *,
+        on_event: Callable[[RunEvent], None] | None,
+    ) -> RunRecord | None:
+        """Persist real host tool receipts on the canonical conversation stream."""
+        started = time.monotonic()
+
+        def envelope(kind: str) -> dict[str, Any]:
+            result = _plugin_event_envelope(record, kind)
+            result["source"] = SourceRef(
+                framework="ksadk",
+                metadata={"runtime": "studio-scheduler", "agent_id": record.agent_id},
+            )
+            return result
+
+        async def publish(event: RuntimeEvent) -> None:
+            persisted = await self.runtime_events.append_one(record.session_id, event)
+            kind, data = project_runtime_event(
+                persisted, session_id=record.session_id, public_run_id=record.id
+            )
+            stored = self.event_store.append(record.id, kind, data)
+            if on_event is not None:
+                on_event(stored)
+
+        call_id = None
+        try:
+            intent = await self.schedule_assistant.plan(
+                record.agent_id,
+                user_input,
+                record.session_id,
+                build_id=record.build_id,
+                model_name=record.model,
+            )
+            if self._cancel_flags.get(record.id):
+                raise asyncio.CancelledError()
+            if intent.action == "ignore":
+                return None
+            record.status = RunStatus.RUNNING
+            record.started_at = datetime.now(timezone.utc)
+            record.runtime_handle = {"provider": "studio-scheduler"}
+            self.event_store.save(record)
+            await publish(RunStarted(**envelope("run.started"), status="running"))
+            call_id = f"{record.id}:schedule"
+            arguments = intent.model_dump(mode="json", exclude_none=True)
+            await publish(
+                ItemStarted(
+                    **envelope("tool.started"),
+                    item_id=call_id,
+                    item_kind="tool_call",
+                    initial=ContentSnapshot(
+                        parts=(
+                            ToolCallContent(
+                                part_id=f"{call_id}:call",
+                                call_id=call_id,
+                                name="studio_schedule",
+                                arguments=arguments,
+                            ),
+                        )
+                    ),
+                )
+            )
+            result = await self.schedule_assistant.execute(
+                record.agent_id, record.session_id, intent
+            )
+            await publish(
+                ItemCompleted(
+                    **envelope("tool.completed"),
+                    item_id=call_id,
+                    item_kind="tool_call",
+                    snapshot=ContentSnapshot(
+                        parts=(
+                            ToolResultContent(
+                                part_id=f"{call_id}:result", call_id=call_id, result=result
+                            ),
+                        )
+                    ),
+                )
+            )
+            output = result["message"]
+            item_id, part_id = f"{record.id}:assistant", f"{record.id}:text"
+            await publish(
+                ItemStarted(
+                    **envelope("item.started"),
+                    item_id=item_id,
+                    item_kind="message",
+                    phase="final_answer",
+                )
+            )
+            await publish(
+                ItemUpdated(
+                    **envelope("item.updated"),
+                    item_id=item_id,
+                    item_kind="message",
+                    op="append",
+                    update=TextContent(part_id=part_id, text=output),
+                )
+            )
+            await publish(
+                ItemCompleted(
+                    **envelope("item.completed"),
+                    item_id=item_id,
+                    item_kind="message",
+                    snapshot=ContentSnapshot(parts=(TextContent(part_id=part_id, text=output),)),
+                )
+            )
+            if intent._usage is not None and intent._usage.reported:
+                record.usage = intent._usage.model_copy(update={"source": "studio-scheduler"})
+                await publish(
+                    UsageReported(
+                        **envelope("usage.reported"),
+                        input_tokens=record.usage.input_tokens,
+                        output_tokens=record.usage.output_tokens,
+                        total_tokens=record.usage.total_tokens,
+                        cached_tokens=record.usage.cached_input_tokens,
+                        reasoning_tokens=record.usage.reasoning_output_tokens,
+                    )
+                )
+            await publish(
+                RunCompleted(
+                    **envelope("run.completed"),
+                    status="completed",
+                    output_refs=(OutputRef(scope_id=record.id, item_id=item_id, part_id=part_id),),
+                )
+            )
+            record.output = output
+            record.status = RunStatus.COMPLETED
+        except asyncio.CancelledError:
+            record.status = RunStatus.CANCELLED
+            record.completed_at = datetime.now(timezone.utc)
+            self._cancel_flags.pop(record.id, None)
+            await publish(
+                RunCanceled(**envelope("run.canceled"), status="canceled", reason="cancelled")
+            )
+            self.event_store.save(record)
+            raise
+        except Exception as error:
+            code = str(getattr(error, "code", "SCHEDULE_REQUEST_FAILED"))
+            record.status = RunStatus.FAILED
+            record.error = {"code": code, "message": str(error)}
+            if call_id is not None:
+                await publish(
+                    ItemFailed(
+                        **envelope("tool.failed"),
+                        item_id=call_id,
+                        item_kind="tool_call",
+                        error=ErrorInfo(
+                            code=code,
+                            message=str(error),
+                            source="studio-scheduler",
+                            scope_id=record.id,
+                        ),
+                    )
+                )
+            await publish(
+                RunFailed(
+                    **envelope("run.failed"),
+                    status="failed",
+                    error=ErrorInfo(
+                        code=code, message=str(error), source="studio-scheduler", scope_id=record.id
+                    ),
+                )
+            )
+        record.completed_at = datetime.now(timezone.utc)
+        record.duration_ms = int((time.monotonic() - started) * 1000)
+        record.duration_source = "studio"
+        self._cancel_flags.pop(record.id, None)
+        self.event_store.save(record)
+        await self._sync_trace(record)
+        return record
+
     async def _sync_trace(self, record: RunRecord) -> None:
         self.event_store.trace_store.sync(record, await self.events(record.id))
 
@@ -531,18 +995,61 @@ class StudioRunService:
             "activationKey": record.session_id,
         }
         self.event_store.save(record)
+        projected_writer = _ProjectedRunEventWriter(self.event_store, record.id, on_event)
         rows_before = await self.session_service.get_events(record.session_id)
         after_seq = max((int(row.seq_id or 0) for row in rows_before), default=0)
+        published_seq = after_seq
 
         async def publish(events: list[RuntimeEvent]) -> None:
+            nonlocal published_seq
             for runtime_event in events:
+                # Harness keeps token-level child output in the canonical
+                # session trace for diagnostics.  It is deliberately not part
+                # of Studio's public run timeline: the activity projection
+                # never consumes these private deltas, and persisting each one
+                # rewrites the growing run JSON file.  Long-running delegated
+                # research can otherwise turn a few useful activity rows into
+                # thousands of O(n²) file writes and make the page appear
+                # frozen.  Advance the cursor so final catch-up will not replay
+                # an omitted delta.
+                if _is_private_harness_delta(runtime_event):
+                    published_seq = max(published_seq, int(runtime_event.seq or 0))
+                    continue
                 event_type, data = project_runtime_event(
                     runtime_event,
                     session_id=record.session_id,
                 )
-                stored = self.event_store.append(record.id, event_type, data)
-                if on_event is not None:
-                    on_event(stored)
+                projected_writer.append(event_type, data)
+                published_seq = max(published_seq, int(runtime_event.seq or 0))
+
+        async def tail_live_events() -> None:
+            # Kernel worker 会把 harness 的增量事实（TEXT_DELTA/ItemUpdated 等）
+            # 在执行期间逐条写入 canonical session store；这里实时转发给 SSE
+            # 订阅端，避免整轮结束后一次性爆发。终态事件会自然结束订阅。
+            async for event in self.runtime_events.subscribe_run(
+                record.session_id,
+                record.id,
+                after_seq=published_seq,
+                poll_interval=0.1,
+                timeout=600,
+            ):
+                try:
+                    await publish([event])
+                except asyncio.CancelledError:
+                    raise
+                except Exception:
+                    logger.exception(
+                        "failed to publish live plugin event for run %s", record.id
+                    )
+
+        tail_task: asyncio.Task[None] | None = None
+
+        async def stop_tail() -> None:
+            nonlocal tail_task
+            if tail_task is not None:
+                tail_task.cancel()
+                await asyncio.gather(tail_task, return_exceptions=True)
+                tail_task = None
 
         try:
             if self.plugin_runtime is None:
@@ -561,18 +1068,22 @@ class StudioRunService:
                 }.items()
                 if value not in {None, ""}
             }
-            result = await self.plugin_runtime.execute(
-                spec,
-                {
-                    "user_id": "local-user",
-                    "session_id": record.session_id,
-                    "invocation_id": record.id,
-                    "messages": [{"role": "user", "content": user_input}],
-                    "model": spec.model,
-                    "request_metadata": request_metadata,
-                },
-                session_id=record.session_id,
-            )
+            tail_task = asyncio.create_task(tail_live_events())
+            try:
+                result = await self.plugin_runtime.execute(
+                    spec,
+                    {
+                        "user_id": "local-user",
+                        "session_id": record.session_id,
+                        "invocation_id": record.id,
+                        "messages": [{"role": "user", "content": user_input}],
+                        "model": spec.model,
+                        "request_metadata": request_metadata,
+                    },
+                    session_id=record.session_id,
+                )
+            finally:
+                await stop_tail()
             if result.session_id != record.session_id:
                 raise StudioError(
                     "PLUGIN_SESSION_MISMATCH",
@@ -585,7 +1096,7 @@ class StudioRunService:
                 )
             canonical = await self._plugin_events_after(
                 record.session_id,
-                after_seq=after_seq,
+                after_seq=published_seq,
                 run_id=record.id,
             )
             if not canonical:
@@ -599,6 +1110,7 @@ class StudioRunService:
             record.status = RunStatus.COMPLETED
             _apply_plugin_usage(record, result.usage)
         except asyncio.CancelledError:
+            await stop_tail()
             record.status = RunStatus.CANCELLED
             record.error = {"code": "RUN_CANCELLED", "message": "运行已取消"}
             cancelled = await self.runtime_events.append_one(
@@ -612,12 +1124,13 @@ class StudioRunService:
             await publish([cancelled])
             raise
         except Exception as exc:  # noqa: BLE001 - plugin boundary is typed below
+            await stop_tail()
             record.status = RunStatus.FAILED
             code = str(getattr(exc, "code", "PLUGIN_RUNTIME_FAILED"))
             record.error = {"code": code, "message": str(exc)}
             canonical = await self._plugin_events_after(
                 record.session_id,
-                after_seq=after_seq,
+                after_seq=published_seq,
                 run_id=record.id,
             )
             if canonical:
@@ -638,6 +1151,7 @@ class StudioRunService:
                 )
                 await publish([failed])
         finally:
+            projected_writer.flush()
             record.completed_at = datetime.now(timezone.utc)
             record.duration_ms = int((time.monotonic() - started) * 1000)
             record.duration_source = "studio"
@@ -672,9 +1186,7 @@ class StudioRunService:
     ) -> list[RuntimeEvent]:
         item_id = f"{record.id}:assistant"
         part_id = f"{record.id}:text"
-        snapshot = ContentSnapshot(
-            parts=(TextContent(part_id=part_id, text=output_text),)
-        )
+        snapshot = ContentSnapshot(parts=(TextContent(part_id=part_id, text=output_text),))
         events: list[RuntimeEvent] = [
             RunStarted(
                 **_plugin_event_envelope(record, "run.started"),
@@ -725,10 +1237,7 @@ class StudioRunService:
                 ),
             )
         )
-        return [
-            await self.runtime_events.append_one(record.session_id, event)
-            for event in events
-        ]
+        return [await self.runtime_events.append_one(record.session_id, event) for event in events]
 
     async def _kernel_run(
         self,
@@ -764,9 +1273,7 @@ class StudioRunService:
                 session_id=record.session_id,
                 operations=("enqueue",),
             )
-            idempotency_key = str(
-                (spec.request_config or {}).get("idempotency_key") or record.id
-            )
+            idempotency_key = str((spec.request_config or {}).get("idempotency_key") or record.id)
             command = _kernel_ingress.map_studio_request(
                 session_id=record.session_id,
                 idempotency_key=idempotency_key,
@@ -774,9 +1281,7 @@ class StudioRunService:
                 run_id=record.id,
                 trusted=trusted,
             )
-            receipt = await _kernel_ingress.submit_command(
-                command, permit=trusted.permit
-            )
+            receipt = await _kernel_ingress.submit_command(command, permit=trusted.permit)
             if receipt.status not in ("accepted", "duplicate"):
                 record.status = RunStatus.FAILED
                 record.error = {
@@ -859,17 +1364,13 @@ class StudioRunService:
         if active_project != build_project:
             return None
         defaults = getattr(runtime.config, "start_request_defaults", {}) or {}
-        bound_agent_id = str(
-            defaults.get("agent_id") or runtime.config.agent_instance_id
-        ).strip()
+        bound_agent_id = str(defaults.get("agent_id") or runtime.config.agent_instance_id).strip()
         if bound_agent_id != spec.agent_id:
             return None
         declared_instance = str(
             (spec.launch_context.config or {}).get("agent_instance_id") or ""
         ).strip()
-        if declared_instance and declared_instance != str(
-            runtime.config.agent_instance_id
-        ):
+        if declared_instance and declared_instance != str(runtime.config.agent_instance_id):
             return None
         return runtime
 
@@ -998,11 +1499,8 @@ class StudioRunService:
                     "同一幂等键不能提交不同内容",
                     status_code=409,
                 )
-            record = self.event_store.get(run_id)
-            if record.status == RunStatus.WAITING_INPUT:
-                record.status = RunStatus.RUNNING
-                self.event_store.save(record)
-                self._waiting_modes.pop(run_id, None)
+            # A receipt replay is read-only. The run may already be waiting
+            # for a different interaction; never clear that newer wait state.
             return dict(prior.data.get("receipt") or {})
 
         interaction = next(
@@ -1039,10 +1537,51 @@ class StudioRunService:
                 status_code=409,
             )
         kind = str(interaction.data.get("kind") or "form")
-        payload_data = {"decision": name, **data}
+        if kind != "approval" and name not in {"cancel", "skip"}:
+            schema = interaction.data.get("inputSchema") or {}
+            errors = list(Draft202012Validator(schema).iter_errors(data))
+            if errors:
+                raise StudioError(
+                    "INTERACTION_RESPONSE_INVALID",
+                    "请填写必填问题后再提交。",
+                    status_code=422,
+                )
+        provider_call_id = str(
+            interaction.data.get("callId") or interaction.data.get("call_id") or ""
+        )
+        if kind == "approval" and not provider_call_id:
+            approval_request = next(
+                (
+                    event
+                    for event in reversed(events)
+                    if event.type == "approval.requested"
+                    and str(event.data.get("approvalId") or event.data.get("interactionId") or "")
+                    == interaction_id
+                ),
+                None,
+            )
+            if approval_request is not None:
+                provider_call_id = str(
+                    approval_request.data.get("callId")
+                    or approval_request.data.get("call_id")
+                    or ""
+                )
+        provider_call_id = provider_call_id or interaction_id
+        submitted = self._submitted_interactions.setdefault(run_id, set())
+        submitted.update({interaction_id, provider_call_id})
+        decision = str(data.get("decision") or name)
+        if kind == "approval" and record.runtime_type == "codex":
+            # The shared Web action is named `reject`; Codex app-server calls
+            # the same decision `deny`/`decline`. Do not let a UI alias fall
+            # through as an unsupported native approval decision.
+            decision = {
+                "reject": "deny",
+                "rejected": "deny",
+            }.get(decision.lower(), decision)
+        payload_data = {**data, "decision": decision}
         payload = ResumePayload(
             kind="approval_decision" if kind == "approval" else "hitl_answer",
-            call_id=interaction_id,
+            call_id=provider_call_id,
             data=payload_data,
         )
         mode = self._waiting_modes.get(run_id)
@@ -1051,8 +1590,19 @@ class StudioRunService:
             if handle is None or not self.executor.is_attached(handle):
                 raise StudioError("INTERACTION_EXPIRED", "运行时交互已失效", status_code=409)
             try:
-                await self.executor.submit(handle, payload)
+                await asyncio.wait_for(
+                    self.executor.submit(handle, payload),
+                    timeout=_INTERACTION_SUBMIT_TIMEOUT_SECONDS,
+                )
+            except TimeoutError as exc:
+                submitted.difference_update({interaction_id, provider_call_id})
+                raise StudioError(
+                    "INTERACTION_SUBMIT_FAILED",
+                    "运行时未及时确认交互提交，请重试",
+                    status_code=409,
+                ) from exc
             except Exception as exc:  # noqa: BLE001 - provider errors are user-safe here
+                submitted.difference_update({interaction_id, provider_call_id})
                 raise StudioError(
                     "INTERACTION_SUBMIT_FAILED",
                     str(exc),
@@ -1065,22 +1615,51 @@ class StudioRunService:
             submit_ack = asyncio.get_running_loop().create_future()
             queue.put_nowait(("resume", payload, submit_ack))
             try:
-                await submit_ack
+                await asyncio.wait_for(
+                    submit_ack,
+                    timeout=_INTERACTION_SUBMIT_TIMEOUT_SECONDS,
+                )
+            except TimeoutError as exc:
+                submitted.difference_update({interaction_id, provider_call_id})
+                raise StudioError(
+                    "INTERACTION_SUBMIT_FAILED",
+                    "运行时未及时确认交互提交，请重试",
+                    status_code=409,
+                ) from exc
             except Exception as exc:  # noqa: BLE001 - provider errors are user-safe here
+                submitted.difference_update({interaction_id, provider_call_id})
                 raise StudioError(
                     "INTERACTION_SUBMIT_FAILED",
                     str(exc),
                     status_code=409,
                 ) from exc
         else:
+            submitted.difference_update({interaction_id, provider_call_id})
             raise StudioError("INTERACTION_EXPIRED", "运行时交互已失效", status_code=409)
 
         next_revision = revision + 1
+        normalized_action = name.lower()
+        if normalized_action in {"approve", "approved", "accept", "accepted"}:
+            outcome = "approved"
+            response_summary = "已同意"
+        elif normalized_action in {"reject", "rejected", "deny", "denied", "decline"}:
+            outcome = "rejected"
+            response_summary = "已拒绝"
+        elif normalized_action in {"cancel", "cancelled", "canceled"}:
+            outcome = "cancelled"
+            response_summary = "已反馈给 Agent" if data.get("feedback") else "已取消"
+        else:
+            outcome = "submitted"
+            response_summary = "已提交"
         resolved_data = {
             "runId": run_id,
             "interactionId": interaction_id,
-            "callId": interaction_id,
+            "callId": provider_call_id,
             "name": name,
+            "action": name,
+            "outcome": outcome,
+            "actor": "user",
+            "responseSummary": response_summary,
             "data": data,
             "revision": next_revision,
             "expectedRevision": expected_revision,
@@ -1092,6 +1671,7 @@ class StudioRunService:
                 interaction.data.get("surfaceId") or interaction.data.get("surface_id") or ""
             ),
             "interactionId": interaction_id,
+            "callId": provider_call_id,
             "actionId": f"action-{interaction_id}",
             "name": name,
             "data": data,
@@ -1111,6 +1691,65 @@ class StudioRunService:
         self._waiting_modes.pop(run_id, None)
         return receipt
 
+    def _expire_unresolved_interactions(
+        self,
+        record: RunRecord,
+        *,
+        on_event: Callable[[RunEvent], None] | None = None,
+    ) -> None:
+        """Close orphaned cards whenever their owning run is terminal."""
+
+        if record.status not in {
+            RunStatus.COMPLETED,
+            RunStatus.FAILED,
+            RunStatus.CANCELLED,
+            RunStatus.INTERRUPTED,
+            RunStatus.TIMED_OUT,
+        }:
+            return
+        events = self.event_store.events(record.id)
+        closed_ids = {
+            str(event.data.get("interactionId") or event.data.get("approvalId") or "")
+            for event in events
+            if event.type
+            in {
+                "a2ui.action",
+                "approval.resolved",
+                "interaction.resolved",
+                "interaction.cancelled",
+                "interaction.expired",
+            }
+        }
+        pending: dict[str, RunEvent] = {}
+        for event in events:
+            if event.type != "a2ui.interaction":
+                continue
+            interaction_id = str(
+                event.data.get("interactionId") or event.data.get("interaction_id") or ""
+            )
+            if interaction_id and interaction_id not in closed_ids:
+                pending[interaction_id] = event
+        for interaction_id, requested in pending.items():
+            data = requested.data
+            expired = self.event_store.append(
+                record.id,
+                "interaction.expired",
+                {
+                    "runId": record.id,
+                    "interactionId": interaction_id,
+                    "approvalId": interaction_id,
+                    "callId": str(data.get("callId") or data.get("call_id") or ""),
+                    "kind": str(data.get("kind") or "form"),
+                    "title": data.get("title"),
+                    "message": data.get("message"),
+                    "detail": data.get("detail"),
+                    "outcome": "expired",
+                    "revision": _interaction_revision(data) + 1,
+                },
+            )
+            if on_event is not None:
+                on_event(expired)
+
     async def _capture_pcm_evidence(
         self,
         record: RunRecord,
@@ -1255,7 +1894,11 @@ class StudioRunService:
                 "runId": record.id,
                 "surfaceId": surface_id,
                 "interactionId": approval_id,
+                "callId": event.request.call_id or approval_id,
                 "kind": "approval",
+                "title": "需要审批",
+                "message": "此次操作需要确认后才能继续。",
+                "detail": detail,
                 "revision": 1,
                 "inputSchema": {
                     "type": "object",
@@ -1284,7 +1927,41 @@ class StudioRunService:
             if previous.agent_id != agent_id or previous.status != RunStatus.COMPLETED:
                 continue
             messages.append({"role": "user", "content": previous.input})
-            messages.append({"role": "assistant", "content": previous.output})
+            assistant_content = previous.output
+            if previous.runtime_type == "harness":
+                projection = project_run_activities(
+                    previous,
+                    self.event_store.events(previous.id),
+                )
+                children = [
+                    activity
+                    for activity in projection.get("activities", [])
+                    if activity.get("kind") == "subagent"
+                ][:8]
+                if children:
+                    status_text = {
+                        "completed": "已完成",
+                        "failed": "失败",
+                        "cancelled": "已取消",
+                        "running": "仍在运行",
+                        "unknown": "状态未确认",
+                    }
+                    facts = "；".join(
+                        f"子智能体“{child.get('label') or '未命名'}”"
+                        f"{status_text.get(str(child.get('status')), '状态未确认')}"
+                        for child in children
+                    )
+                    # Lifecycle evidence belongs to the completed assistant turn.
+                    # A standalone system message inserted between historical turns
+                    # can outweigh the next user request on some providers and make
+                    # a new turn answer an old child result instead (conversation
+                    # "cross-talk"). Keep the evidence attached to the turn it
+                    # describes so the newest user message remains authoritative.
+                    assistant_content = (
+                        f"{assistant_content}\n\n"
+                        f"[Harness 执行记录] {facts}。"
+                    )
+            messages.append({"role": "assistant", "content": assistant_content})
         messages.append({"role": "user", "content": user_input})
         return messages
 
@@ -1293,16 +1970,30 @@ class StudioRunService:
         agent_id: str,
         session_id: str,
         runtime_type: str,
+        build_id: str,
     ) -> dict[str, str]:
         if runtime_type != "codex":
             return {}
-        for previous in self.event_store.list_runs(session_id=session_id):
-            if previous.agent_id != agent_id or previous.status != RunStatus.COMPLETED:
-                continue
+        runs = self.event_store.list_runs(session_id=session_id, agent_id=agent_id)
+        thread_builds: dict[str, str] = {}
+        for previous in runs:
+            native_ref = previous.runtime_handle.get("native_ref") or {}
+            if isinstance(native_ref, dict) and native_ref.get("thread_id"):
+                # Older Studio versions also saved failed cross-build resumes.
+                # The first occurrence identifies the thread's actual home.
+                thread_builds.setdefault(str(native_ref["thread_id"]), previous.build_id)
+        for previous in reversed(runs):
+            # Each immutable build has its own CODEX_HOME and plugin snapshot.
+            # Starting a thread in that home applies the new capabilities; the
+            # transport-neutral history above preserves the Studio conversation.
+            if previous.build_id != build_id:
+                return {}
             native_ref = previous.runtime_handle.get("native_ref")
             native_ref = native_ref if isinstance(native_ref, dict) else {}
             thread_id = str(native_ref.get("thread_id") or "")
             if thread_id:
+                if thread_builds[thread_id] != build_id:
+                    return {}
                 return {"thread_id": thread_id}
         return {}
 
@@ -1340,17 +2031,13 @@ def _normalized_plugin_usage(usage: Mapping[str, Any]) -> dict[str, Any]:
 
     normalized = {
         "input_tokens": number("input_tokens", "inputTokens", "prompt_tokens"),
-        "output_tokens": number(
-            "output_tokens", "outputTokens", "completion_tokens"
-        ),
+        "output_tokens": number("output_tokens", "outputTokens", "completion_tokens"),
         "total_tokens": number("total_tokens", "totalTokens"),
         "cached_tokens": number("cached_tokens", "cachedTokens"),
         "reasoning_tokens": number("reasoning_tokens", "reasoningTokens"),
     }
     if not normalized["total_tokens"]:
-        normalized["total_tokens"] = (
-            normalized["input_tokens"] + normalized["output_tokens"]
-        )
+        normalized["total_tokens"] = normalized["input_tokens"] + normalized["output_tokens"]
     normalized["reported"] = bool(usage) and any(
         key in usage
         for key in (
@@ -1391,6 +2078,25 @@ def _apply_plugin_usage(record: RunRecord, usage: Mapping[str, Any]) -> None:
     )
 
 
+def _is_private_harness_delta(event: RuntimeEvent) -> bool:
+    """Return whether *event* is an internal token delta, not a UI activity.
+
+    Managed Harness projects its rich event stream to canonical status items.
+    ``text.delta`` and ``reasoning.delta`` contain private token fragments,
+    are intentionally ignored by ``run_activity``, and must not be copied into
+    Studio's durable session or run stores. User-visible parent answer
+    streaming uses canonical ``message`` items and therefore remains
+    unaffected.
+    """
+
+    if not isinstance(event, ItemCompleted) or event.item_kind != "status":
+        return False
+    if event.source.framework != "ksadk":
+        return False
+    native_event_type = str(event.source.metadata.get("native_event_type") or "")
+    return native_event_type in {"reasoning.delta", "text.delta"}
+
+
 def project_runtime_event(
     event: RuntimeEvent,
     *,
@@ -1520,7 +2226,9 @@ def project_runtime_event(
             payload = {
                 "interactionId": event.interaction_id,
                 "kind": "form",
-                "inputSchema": {},
+                "inputSchema": event.request.schema_,
+                "message": event.request.prompt or "",
+                "callId": event.source.native_event_id or event.interaction_id,
             }
     elif isinstance(event, InteractionResolved):
         if event.interaction_kind == "approval":
@@ -1575,9 +2283,7 @@ def project_runtime_event(
     return projected, payload
 
 
-def _first_content(
-    snapshot: ContentSnapshot | None, content_type: type
-) -> Any | None:
+def _first_content(snapshot: ContentSnapshot | None, content_type: type) -> Any | None:
     if snapshot is None:
         return None
     for part in snapshot.parts: