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

ksadk/studio/shared_web.py

@@ -22,10 +22,14 @@ from ksadk.conversations.message_projection import project_session_messages
 from ksadk.events.canonical import parse_runtime_event
 from ksadk.events.canonical_store import session_event_to_runtime_event
 from ksadk.sessions.base import Session
-from ksadk.studio.contracts import OperationStatus, RunRecord, RunStatus
+from ksadk.studio import shared_web_run_state as run_state
+from ksadk.studio.active_run_output import active_run_output
+from ksadk.studio.contracts import OperationStatus, RunRecord, RunStatus, RunSubmissionRef
 from ksadk.studio.errors import StudioError, not_found
+from ksadk.studio.run_documents import link_run_documents
 from ksadk.studio.run_service import project_runtime_event
 from ksadk.studio.service import StudioService
+from ksadk.studio.shared_web_response_events import project_response_events
 from ksadk.tools.gateway import tool_approval_capability
 
 _TERMINAL_OPERATIONS = {
@@ -67,6 +71,13 @@ class StudioSharedWebBridge:
             "ApiFormats": ["responses"],
             "Model": model,
             "Capabilities": {
+                "ConversationPresentation": {
+                    "Timeline": "compact"
+                    if self.studio.agent_runtime_type(agent_id) == "harness"
+                    else "standard",
+                },
+                "RuntimePrewarm": self.studio.agent_runtime_type(agent_id) == "harness",
+                "StudioRunReceiptQuery": True,
                 "HostedChat": {
                     "Enabled": True,
                     "ApiFormats": ["responses"],
@@ -95,6 +106,8 @@ class StudioSharedWebBridge:
                 },
                 "ApprovalPolicy": tool_approval_capability(),
                 "InteractionV1": True,
+                "SteerRun": self.studio.agent_runtime_type(agent_id).strip().lower()
+                == "harness",
                 "WorkspaceFiles": {"Enabled": False},
                 "NativeDashboard": {"Enabled": False},
                 "NativeTerminal": {"Enabled": False},
@@ -146,6 +159,7 @@ class StudioSharedWebBridge:
         return {"Session": self._session_metadata_record(session)}
 
     async def get_session(self, session_id: str) -> dict[str, Any]:
+        self.studio._require_direct_session(session_id)
         runs = self.studio.event_store.list_runs(session_id=session_id)
         if runs:
             return {"Session": self._session_record(runs)}
@@ -155,6 +169,7 @@ class StudioSharedWebBridge:
         return {"Session": self._session_metadata_record(session)}
 
     async def compact_session(self, agent_id: str, session_id: str) -> dict[str, Any]:
+        self.studio._require_direct_session(session_id)
         from ksadk.codex.runtime import CodexRuntimeAdapter
 
         runs = self.studio.event_store.list_runs(session_id=session_id, agent_id=agent_id)
@@ -218,6 +233,7 @@ class StudioSharedWebBridge:
         before_seq_id: int | None = None,
         limit: int = 50,
     ) -> dict[str, Any]:
+        self.studio._require_direct_session(session_id)
         runs = self.studio.event_store.list_runs(session_id=session_id)
         messages: list[dict[str, Any]] = []
         sequence = 0
@@ -233,6 +249,25 @@ class StudioSharedWebBridge:
                     "InvocationId": run.id,
                 }
             )
+            last_steer_at = None
+            for event in self.studio.event_store.events(run.id):
+                if event.type != "run.steer_requested":
+                    continue
+                text = event.data.get("text")
+                if not isinstance(text, str) or not text:
+                    continue
+                sequence += 1
+                last_steer_at = event.created_at
+                messages.append(
+                    {
+                        "MessageId": f"{run.id}:steer:{event.id}",
+                        "Role": "user",
+                        "Content": {"text": text},
+                        "Timestamp": self._timestamp(event.created_at),
+                        "SeqId": sequence,
+                        "InvocationId": run.id,
+                    }
+                )
             sequence += 1
             messages.append(
                 {
@@ -242,11 +277,17 @@ class StudioSharedWebBridge:
                         # Run status is metadata, not an assistant reply. An
                         # empty pending reply lets canonical reasoning/tools
                         # restore without a synthetic status text shadowing them.
-                        "text": (
-                            run.output if self._active_status(run.status) else self._run_output(run)
+                        "text": link_run_documents(
+                            self.studio,
+                            run,
+                            await active_run_output(self.studio.run_service, run)
+                            if self._active_status(run.status)
+                            else self._run_output(run),
                         )
                     },
-                    "Timestamp": self._timestamp(run.completed_at or run.started_at),
+                    "Timestamp": self._timestamp(
+                        run.completed_at or last_steer_at or run.started_at
+                    ),
                     "SeqId": sequence,
                     "InvocationId": run.id,
                     "Activities": await self._run_activities(run),
@@ -279,6 +320,7 @@ class StudioSharedWebBridge:
         }
 
     async def list_session_events(self, session_id: str) -> dict[str, Any]:
+        self.studio._require_direct_session(session_id)
         runs = self.studio.event_store.list_runs(session_id=session_id)
         events: list[dict[str, Any]] = []
         sequence = 0
@@ -290,7 +332,7 @@ class StudioSharedWebBridge:
                         "SeqId": sequence,
                         "EventType": self._shared_event_type(event.type, event.data),
                         "InvocationId": run.id,
-                        "Content": self._shared_event_content(event.data, run.id),
+                        "Content": self._presentation_event_content(event.data, run),
                         "Timestamp": self._timestamp(event.created_at),
                     }
                 )
@@ -386,7 +428,72 @@ class StudioSharedWebBridge:
             return data
         return {**data, "runtimeEvent": {**native, "run_id": run_id}}
 
+    def _presentation_event_content(self, data: dict[str, Any], run: RunRecord) -> dict[str, Any]:
+        content = self._shared_event_content(data, run.id)
+        native = content.get("runtimeEvent")
+        if run.runtime_type != "harness" or not isinstance(native, dict):
+            return content
+        native = dict(native)
+        source_metadata = native.get("source", {}).get("metadata", {})
+        native_type = source_metadata.get(
+            "native_event_type", source_metadata.get("native_event_kind")
+        )
+        if native_type == "run.progress" and native.get("item_kind") == "message":
+            # Progress is an activity, never assistant answer prose. This also
+            # repairs historical runs without rewriting their audit transcript.
+            native["item_kind"] = "reasoning"
+        if (
+            native_type == "text.completed"
+            and native.get("item_kind") == "message"
+            and source_metadata.get("phase") == "final_answer"
+            and run.output
+            and not self._active_status(run.status)
+        ):
+            snapshot = native.get("snapshot") or {}
+            text = "".join(
+                str(part.get("text") or "")
+                for part in snapshot.get("parts", [])
+                if part.get("content_type") == "text"
+            )
+            if text and text != run.output:
+                # Older Harness runs projected compaction summaries through
+                # the same final item as the actual answer.  The durable run
+                # output is the terminal authority; retain the legacy event as
+                # redacted trace state so refresh cannot restore stale prose.
+                native["item_kind"] = "status"
+                native["snapshot"] = {
+                    **snapshot,
+                    "parts": [
+                        {
+                            **part,
+                            "text": json.dumps(
+                                {
+                                    "event": "text.completed",
+                                    "details": {"purpose": "non_authoritative_final"},
+                                },
+                                ensure_ascii=False,
+                                separators=(",", ":"),
+                            ),
+                        }
+                        if part.get("content_type") == "text"
+                        else part
+                        for part in snapshot.get("parts", [])
+                    ],
+                }
+        if native_type == "text.completed" and native.get("snapshot"):
+            native["snapshot"] = {
+                **native["snapshot"],
+                "parts": [
+                    {**part, "text": link_run_documents(self.studio, run, part["text"])}
+                    if part.get("content_type") == "text"
+                    else part
+                    for part in native["snapshot"].get("parts", [])
+                ],
+            }
+        return {**content, "runtimeEvent": native}
+
     async def subscription_run_id(self, session_id: str, invocation_id: str) -> str:
+        self.studio._require_direct_session(session_id)
         run_id = self._run_ids_by_invocation.get(invocation_id, invocation_id)
         try:
             run = self.studio.event_store.get(run_id)
@@ -440,7 +547,12 @@ class StudioSharedWebBridge:
                 break
             offset += len(self.studio.event_store.events(record.id))
         cursor = max(0, after_seq_id - offset)
+        control_sent = False
         while True:
+            control = run_state.control_ready_event(self.studio, run_id, invocation_id)
+            if control and not control_sent:
+                yield self._sse(*control)
+                control_sent = True
             for event in await self.studio.run_service.events(run_id, after=cursor):
                 cursor = max(cursor, event.id)
                 yield self._sse(
@@ -450,7 +562,9 @@ class StudioSharedWebBridge:
                         "SessionId": session_id,
                         "InvocationId": invocation_id,
                         "EventType": self._shared_event_type(event.type, event.data),
-                        "Content": self._shared_event_content(event.data, run_id),
+                        "Content": self._presentation_event_content(
+                            event.data, self.studio.event_store.get(run_id)
+                        ),
                         "Timestamp": self._timestamp(event.created_at),
                     },
                 )
@@ -461,43 +575,294 @@ class StudioSharedWebBridge:
             yield ": ping\n\n"
             await asyncio.sleep(0.25)
 
-    def cancel_run(self, invocation_id: str) -> dict[str, Any]:
+    async def cancel_run(self, invocation_id: str) -> dict[str, Any]:
         operation_id = self._operations_by_invocation.get(invocation_id)
-        if operation_id:
+        run_id = run_state.resolve_cancel_run_id(
+            self.studio,
+            invocation_id,
+            self._run_ids_by_invocation,
+            self._response_runs,
+        )
+        if run_id is None and operation_id is None:
+            client_id = next((
+                client_id
+                for client_id, canonical_id in self._run_ids_by_invocation.items()
+                if canonical_id == invocation_id and client_id in self._operations_by_invocation
+            ), None)
+            if client_id is not None:
+                operation_id = self._operations_by_invocation[client_id]
+                run_id = invocation_id
+        self.studio._require_direct_run(run_id or invocation_id)
+        if run_id:
+            # Preserve the canonical Run terminal event. Cancelling only the
+            # outer Operation can strand the already-created Run in CREATED.
+            await self.studio.run_service.cancel_run(run_id)
+            # ListSessions is refreshed as soon as this response returns. Give
+            # the run task a short bounded window to persist its terminal state
+            # so the sidebar does not keep a stale "running" indicator.
+            event_store = getattr(self.studio, "event_store", None)
+            if event_store is not None:
+                # Provider cancellation may need to unwind an in-flight model
+                # request before RunService can append run.canceled.  Keep the
+                # CancelRun response pending for a bounded 10 seconds so the
+                # refresh issued by ksadk-web observes the terminal record
+                # instead of permanently caching a transient RUNNING badge.
+                for _ in range(200):
+                    try:
+                        status = event_store.get(run_id).status
+                    except Exception:  # noqa: BLE001 - cancellation already accepted
+                        break
+                    if status not in {
+                        RunStatus.CREATED,
+                        RunStatus.RUNNING,
+                        RunStatus.WAITING_INPUT,
+                    }:
+                        break
+                    await asyncio.sleep(0.05)
+        elif operation_id:
             self.studio.operations.cancel(operation_id)
-        return {"InvocationId": invocation_id, "Cancelled": bool(operation_id)}
+        return {
+            "InvocationId": invocation_id,
+            "RunId": run_id or "",
+            "Cancelled": bool(run_id or operation_id),
+        }
 
     async def pause_run(self, invocation_id: str) -> dict[str, Any]:
+        self.studio._require_direct_run(invocation_id)
         run_id = self._run_ids_by_invocation.get(invocation_id)
         if not run_id:
             raise StudioError("RUN_NOT_READY", "运行尚未创建，请稍后重试", status_code=409)
         return await self.studio.run_service.pause_run(run_id)
 
+    async def steer_run(
+        self, invocation_id: str, text: str, *, delivery: str = "replace"
+    ) -> dict[str, Any]:
+        run_id = self.resolve_run_reference(invocation_id)
+        self.studio._require_direct_run(run_id)
+        result = await self.studio.run_service.steer_run(run_id, text, delivery=delivery)
+        message_id = f"{run_id}:steer:{result['eventId']}" if result.get("eventId") else None
+        return {
+            "InvocationId": invocation_id,
+            "RunId": result["runId"],
+            "Status": result["status"],
+            **({"MessageId": message_id} if message_id else {}),
+        }
+
     async def resume_run(self, invocation_id: str) -> dict[str, Any]:
+        self.studio._require_direct_run(invocation_id)
         run_id = self._run_ids_by_invocation.get(invocation_id)
         if not run_id:
             raise StudioError("RUN_NOT_FOUND", "未找到可继续的运行", status_code=404)
         return await self.studio.run_service.resume_run(run_id)
 
     def response_session_id(self, response_id: str) -> str:
-        run_id = self._response_runs.get(response_id, response_id)
+        run_id = (
+            self._run_ids_by_invocation.get(response_id)
+            or self._response_runs.get(response_id)
+            or response_id
+        )
         return self.studio.event_store.get(run_id).session_id
 
+    def resolve_run_reference(self, reference: str) -> str:
+        """Resolve a live Responses invocation without guessing the latest run."""
+        return run_state.resolve_run_reference(
+            self._run_ids_by_invocation, self._response_runs, reference
+        )
+
+    def run_receipt(self, agent_id: str, session_id: str, invocation_id: str) -> dict[str, Any]:
+        from ksadk.studio.run_submission_receipts import submission_receipt
+
+        return submission_receipt(
+            self.studio,
+            RunSubmissionRef(
+                client_invocation_id=invocation_id, agent_id=agent_id, session_id=session_id
+            ),
+        )
+
+    async def _submit_response_resume(
+        self,
+        *,
+        previous_response_id: str,
+        response_id: str,
+        resume_input: dict[str, Any],
+    ) -> RunRecord:
+        """Resolve one Responses approval item through Interaction/v1."""
+
+        if str(resume_input.get("type") or "") != "mcp_approval_response":
+            raise StudioError(
+                "RESPONSE_RESUME_UNSUPPORTED",
+                "Studio 当前只支持 MCP 审批恢复",
+                status_code=422,
+            )
+        run_id = self.resolve_run_reference(previous_response_id)
+        record = self.studio.event_store.get(run_id)
+        requested_id = str(
+            resume_input.get("approval_request_id") or resume_input.get("id") or ""
+        )
+        events = self.studio.event_store.events(run_id)
+        resolved_ids = {
+            str(event.data.get("interactionId") or event.data.get("interaction_id") or "")
+            for event in events
+            if event.type in {"a2ui.action", "interaction.resolved"}
+        }
+        pending = [
+            event
+            for event in events
+            if event.type == "a2ui.interaction"
+            and str(
+                event.data.get("interactionId") or event.data.get("interaction_id") or ""
+            )
+            not in resolved_ids
+        ]
+        interaction = next(
+            (
+                event
+                for event in reversed(pending)
+                if not requested_id
+                or requested_id
+                in {
+                    str(
+                        event.data.get("interactionId")
+                        or event.data.get("interaction_id")
+                        or ""
+                    ),
+                    str(event.data.get("callId") or event.data.get("call_id") or ""),
+                }
+            ),
+            None,
+        )
+        if interaction is None:
+            raise StudioError(
+                "INTERACTION_NOT_FOUND",
+                "未找到待处理的审批请求",
+                status_code=404,
+            )
+        interaction_id = str(
+            interaction.data.get("interactionId")
+            or interaction.data.get("interaction_id")
+            or ""
+        )
+        revision = int(interaction.data.get("revision") or 1)
+        approved = bool(resume_input.get("approve"))
+        action = "approve" if approved else "reject"
+        data: dict[str, Any] = {"decision": action}
+        if resume_input.get("reason") is not None:
+            data["reason"] = str(resume_input.get("reason") or "")
+        await self.studio.run_service.submit_interaction(
+            run_id,
+            interaction_id,
+            name=action,
+            data=data,
+            expected_revision=revision,
+            idempotency_key=f"responses:{response_id}:{interaction_id}:{revision}",
+        )
+        self._run_ids_by_invocation[response_id] = run_id
+        self._response_runs[response_id] = run_id
+        return record
+
+    async def _wait_for_resumed_response(self, run_id: str) -> RunRecord:
+        while True:
+            run = self.studio.event_store.get(run_id)
+            if run.status == RunStatus.COMPLETED:
+                return run
+            if run.status in {RunStatus.FAILED, RunStatus.CANCELLED}:
+                raise StudioError("RUN_FAILED", self._run_output(run), status_code=500)
+            await asyncio.sleep(0.05)
+
+    async def stream_response_resume(
+        self,
+        *,
+        previous_response_id: str,
+        response_id: str,
+        resume_input: dict[str, Any],
+    ) -> AsyncIterator[str]:
+        try:
+            record = await self._submit_response_resume(
+                previous_response_id=previous_response_id,
+                response_id=response_id,
+                resume_input=resume_input,
+            )
+            model = str(record.model or "")
+            yield run_state.created_response_sse(
+                response_id,
+                model=model,
+                encode=self._sse,
+                response_shell=self._response_shell,
+            )
+            yield self._sse(
+                "response.in_progress",
+                {
+                    "type": "response.in_progress",
+                    "response": self._response_shell(response_id, model=model),
+                },
+            )
+            wait_task = asyncio.create_task(self._wait_for_resumed_response(record.id))
+            while not wait_task.done():
+                yield ": keep-alive\n\n"
+                await asyncio.sleep(1)
+            run = await wait_task
+            if run.output:
+                yield self._response_delta_sse(
+                    "response.output_text.delta",
+                    invocation_id=response_id,
+                    delta=run.output,
+                )
+            yield self._sse(
+                "response.completed",
+                {
+                    "type": "response.completed",
+                    "response": self._response_payload(
+                        run,
+                        model=model,
+                        response_id=response_id,
+                    ),
+                },
+            )
+        except StudioError as exc:
+            yield self._failed_sse(response_id, exc.message)
+
+    async def invoke_response_resume(
+        self,
+        *,
+        previous_response_id: str,
+        response_id: str,
+        resume_input: dict[str, Any],
+    ) -> dict[str, Any]:
+        record = await self._submit_response_resume(
+            previous_response_id=previous_response_id,
+            response_id=response_id,
+            resume_input=resume_input,
+        )
+        run = await self._wait_for_resumed_response(record.id)
+        return self._response_payload(
+            run,
+            model=str(run.model or record.model or ""),
+            response_id=response_id,
+        )
+
     async def stream_run(
         self, payload: dict[str, Any], *, shared_ui: bool = False
     ) -> AsyncIterator[str]:
-        agent_id = self.resolve_agent_id(str(payload.get("AgentId") or "") or None)
         session_id = str(payload.get("SessionId") or f"ses_{uuid4().hex}")
         invocation_id = str(payload.get("InvocationId") or f"resp_{uuid4().hex}")
-        prompt = self._input_text(payload)
-        runtime_input = self._runtime_input(payload)
-        model = self._select_model(agent_id, str(payload.get("Model") or ""))
-        model_explicit = bool(payload.get("ModelExplicit", str(payload.get("Model") or "")))
-        approval_mode, collaboration_mode, goal_objective, reasoning_effort = (
-            self._request_controls(payload)
-        )
+        # Keep the client correlation key through the operation layer. It is
+        # only an idempotency key when the caller explicitly supplies one;
+        # otherwise each invocation remains independently executable.
+        idempotency_key = str(payload.get("IdempotencyKey") or f"responses:{invocation_id}")
         try:
+            agent_id = self.resolve_agent_id(str(payload.get("AgentId") or "") or None)
+            prompt = self._input_text(payload)
+            runtime_input = self._runtime_input(payload)
+            # A cold provider-backed Agent may not have populated the mutable
+            # provider catalog yet.  Building first performs the authoritative
+            # discovery and freezes the resolved model into the Build; model
+            # validation must therefore happen after this step.
             build = await self._ensure_build(agent_id)
+            model = self._select_build_model(build, str(payload.get("Model") or ""))
+            model_explicit = bool(payload.get("ModelExplicit", str(payload.get("Model") or "")))
+            approval_mode, collaboration_mode, goal_objective, reasoning_effort = (
+                self._request_controls(payload)
+            )
             self._validate_conversation_turn(
                 build_id=build.id,
                 session_id=session_id,
@@ -533,24 +898,21 @@ class StudioSharedWebBridge:
                 collaboration_mode=collaboration_mode,
                 goal_objective=goal_objective,
                 reasoning_effort=reasoning_effort,
+                idempotency_key=idempotency_key,
             )
         )
 
-        def release_operation(task: asyncio.Task[RunRecord]) -> None:
-            self._operations_by_invocation.pop(invocation_id, None)
-            if not task.cancelled():
-                task.exception()
-
-        execution.add_done_callback(release_operation)
-
-        yield self._sse(
-            "response.created",
-            {
-                "type": "response.created",
-                "response": self._response_shell(invocation_id, model=model),
-            },
-        )
+        run_state.attach_release_callback(execution, self._operations_by_invocation, invocation_id)
         try:
+            await run_state.wait_for_durable_run(
+                execution,
+                self._run_ids_by_invocation,
+                invocation_id,
+                self._operations_by_invocation,
+            )
+            yield run_state.created_response_sse(
+                invocation_id, model=model, encode=self._sse, response_shell=self._response_shell
+            )
             yield self._sse(
                 "response.in_progress",
                 {
@@ -574,15 +936,9 @@ class StudioSharedWebBridge:
                         if event_name == "response.output_text.delta":
                             emitted_text += str(event_payload.get("delta") or "")
                         yield self._sse(event_name, event_payload)
-                        if (
-                            shared_ui
-                            and event_name == "a2ui.interaction"
-                            and event_payload.get("kind") in {"form", "structured_input"}
-                        ):
-                            # The shared UI restores the durable Interaction/v1
-                            # request, then subscribes to this same live run.
-                            # Leave the execution attached while input is pending.
-                            return
+                        # A form pauses the Agent, not its response stream.
+                        # Keep delivery attached through input and emit the
+                        # eventual terminal frame after the same run resumes.
                 else:
                     idle_polls += 1
                     if idle_polls >= 20:
@@ -608,19 +964,32 @@ class StudioSharedWebBridge:
                     invocation_id=invocation_id,
                     delta=remaining,
                 )
+            response = self._response_payload(run, model=model, response_id=invocation_id)
+            # A delta can be a provisional model preview. Responses clients may
+            # suppress response.completed's text after any delta, so publish the
+            # committed (and document-linked) replacement explicitly first.
+            yield self._sse(
+                "response.output_text.done",
+                {
+                    "type": "response.output_text.done",
+                    "item_id": f"msg_{invocation_id}",
+                    "output_index": 0,
+                    "content_index": 0,
+                    "text": response["output"][0]["content"][0]["text"],
+                },
+            )
             yield self._sse(
                 "response.completed",
                 {
                     "type": "response.completed",
-                    "response": self._response_payload(
-                        run,
-                        model=model,
-                        response_id=invocation_id,
-                    ),
+                    "response": response,
                 },
             )
         except StudioError as exc:
-            yield self._failed_sse(invocation_id, exc.message)
+            if exc.code == "RUN_CANCELLED":
+                yield run_state.cancelled_response_sse(invocation_id, encode=self._sse)
+            else:
+                yield self._failed_sse(invocation_id, exc.message)
         except Exception:
             yield self._failed_sse(invocation_id, "本地 Agent 运行失败")
         finally:
@@ -633,12 +1002,15 @@ class StudioSharedWebBridge:
         agent_id = self.resolve_agent_id(str(payload.get("AgentId") or "") or None)
         session_id = str(payload.get("SessionId") or f"ses_{uuid4().hex}")
         invocation_id = str(payload.get("InvocationId") or f"resp_{uuid4().hex}")
-        model = self._select_model(agent_id, str(payload.get("Model") or ""))
+        idempotency_key = str(payload.get("IdempotencyKey") or f"responses:{invocation_id}")
+        # Keep the non-streaming entry point consistent with stream_run: a
+        # cold Build is what discovers provider-backed models.
+        build = await self._ensure_build(agent_id)
+        model = self._select_build_model(build, str(payload.get("Model") or ""))
         model_explicit = bool(payload.get("ModelExplicit", str(payload.get("Model") or "")))
         approval_mode, collaboration_mode, goal_objective, reasoning_effort = (
             self._request_controls(payload)
         )
-        build = await self._ensure_build(agent_id)
         prompt = self._input_text(payload)
         runtime_input = self._runtime_input(payload)
         self._validate_conversation_turn(
@@ -666,6 +1038,7 @@ class StudioSharedWebBridge:
                 collaboration_mode=collaboration_mode,
                 goal_objective=goal_objective,
                 reasoning_effort=reasoning_effort,
+                idempotency_key=idempotency_key,
             )
             return self._response_payload(
                 run,
@@ -689,6 +1062,7 @@ class StudioSharedWebBridge:
         collaboration_mode: str = "",
         goal_objective: str = "",
         reasoning_effort: str = "",
+        idempotency_key: str = "",
     ) -> RunRecord:
         if build is None:
             build = await self._ensure_build(agent_id)
@@ -716,8 +1090,11 @@ class StudioSharedWebBridge:
             goal_objective=goal_objective or None,
             reasoning_effort=reasoning_effort or None,
             runtime_input=runtime_input or None,
-            idempotency_key=f"responses:{invocation_id}",
+            idempotency_key=idempotency_key or f"responses:{invocation_id}",
             on_event=observe,
+            submission_ref=RunSubmissionRef(
+                client_invocation_id=invocation_id, agent_id=agent_id, session_id=session_id
+            ),
         )
         self._operations_by_invocation[invocation_id] = operation.id
         while True:
@@ -726,23 +1103,14 @@ class StudioSharedWebBridge:
                 break
             await asyncio.sleep(0.05)
         if current.status != OperationStatus.SUCCEEDED:
-            message = str((current.error or {}).get("message") or "Agent 运行失败")
-            raise StudioError("RUN_FAILED", message, status_code=500)
+            run_state.raise_for_unsuccessful_operation(self.studio, current)
         run = self.studio.event_store.get(current.resource_id)
         if run.status != RunStatus.COMPLETED:
             raise StudioError("RUN_FAILED", self._run_output(run), status_code=500)
         self._response_runs[invocation_id] = run.id
         return run
 
-    @staticmethod
-    def _response_shell(response_id: str, *, model: str) -> dict[str, Any]:
-        return {
-            "id": response_id,
-            "object": "response",
-            "status": "in_progress",
-            "model": model,
-            "output": [],
-        }
+    _response_shell = staticmethod(run_state.response_shell)
 
     async def _project_response_events(
         self,
@@ -752,101 +1120,9 @@ class StudioSharedWebBridge:
         invocation_id: str,
         seen: set[tuple[str, int]],
     ) -> list[tuple[str, dict[str, Any]]]:
-        projected: list[tuple[str, dict[str, Any]]] = []
-        current_run_id = self._run_ids_by_invocation.get(invocation_id)
-        if not current_run_id:
-            return projected
-        for run in self.studio.event_store.list_runs(session_id=session_id):
-            if run.agent_id != agent_id or run.id != current_run_id:
-                continue
-            events = await self.studio.run_service.events(run.id)
-            starts = {
-                str(event.data.get("callId") or event.data.get("call_id") or ""): event.data
-                for event in events
-                if event.type in {"command.started", "tool.started", "tool.requested"}
-            }
-            for event in events:
-                key = (run.id, event.id)
-                if key in seen:
-                    continue
-                seen.add(key)
-                if event.type in {"message.delta", "thinking.delta"}:
-                    delta = str(event.data.get("text") or event.data.get("delta") or "")
-                    if not delta:
-                        continue
-                    event_name = (
-                        "response.output_text.delta"
-                        if event.type == "message.delta"
-                        else "response.reasoning_summary_text.delta"
-                    )
-                    projected.append(
-                        (
-                            event_name,
-                            self._response_delta_payload(
-                                event_name,
-                                invocation_id=invocation_id,
-                                delta=delta,
-                            ),
-                        )
-                    )
-                    continue
-                if event.type.startswith("a2ui."):
-                    projected.append(
-                        (
-                            event.type,
-                            {
-                                "type": event.type,
-                                "runId": run.id,
-                                **event.data,
-                            },
-                        )
-                    )
-                    continue
-                if event.type == "run.paused":
-                    projected.append(
-                        (
-                            "response.paused",
-                            {
-                                "type": "response.paused",
-                                "response_id": invocation_id,
-                                "runId": run.id,
-                            },
-                        )
-                    )
-                    continue
-                if event.type == "run.resumed":
-                    projected.append(
-                        (
-                            "response.resumed",
-                            {
-                                "type": "response.resumed",
-                                "response_id": invocation_id,
-                                "runId": run.id,
-                            },
-                        )
-                    )
-                    continue
-                if event.type == "approval.resolved":
-                    projected.append(
-                        (
-                            "response.ksadk.approval_resolved",
-                            {
-                                "type": "response.ksadk.approval_resolved",
-                                "approvalRequestId": event.data.get("approvalId")
-                                or event.data.get("interactionId"),
-                                "decision": event.data.get("decision")
-                                or event.data.get("name")
-                                or "approved",
-                                "revision": event.data.get("revision") or 2,
-                                "runId": run.id,
-                            },
-                        )
-                    )
-                    continue
-                item_event = self._response_item_event(event.type, event.data, starts)
-                if item_event is not None:
-                    projected.append(item_event)
-        return projected
+        return await project_response_events(
+            self, session_id=session_id, agent_id=agent_id, invocation_id=invocation_id, seen=seen
+        )
 
     @staticmethod
     def _response_item_event(
@@ -862,6 +1138,9 @@ class StudioSharedWebBridge:
             "command.failed",
             "tool.failed",
         }
+        failed = event_type.endswith("failed") or str(data.get("status") or "").lower() in {
+            "failed", "error", "uncertain",
+        }
         if event_type.startswith("command."):
             command = str(data.get("command") or started.get("command") or "执行命令")
             item = {
@@ -870,7 +1149,7 @@ class StudioSharedWebBridge:
                 "type": "shell_call",
                 "status": (
                     "failed"
-                    if event_type.endswith("failed") or data.get("exitCode") not in {None, 0}
+                    if failed or data.get("exitCode") not in {None, 0}
                     else "completed"
                     if done
                     else "in_progress"
@@ -893,7 +1172,7 @@ class StudioSharedWebBridge:
                 "arguments": json.dumps(args, ensure_ascii=False) if args is not None else "",
                 "status": (
                     "failed"
-                    if event_type.endswith("failed")
+                    if failed
                     else "completed"
                     if done
                     else "in_progress"
@@ -948,8 +1227,8 @@ class StudioSharedWebBridge:
             "delta": delta,
         }
 
-    @staticmethod
     def _response_payload(
+        self,
         run: RunRecord,
         *,
         model: str,
@@ -969,7 +1248,7 @@ class StudioSharedWebBridge:
                     "content": [
                         {
                             "type": "output_text",
-                            "text": run.output,
+                            "text": link_run_documents(self.studio, run, run.output),
                             "annotations": [],
                         }
                     ],
@@ -1086,16 +1365,20 @@ class StudioSharedWebBridge:
             session.id: self._session_metadata_record(session)
             for session in persisted
             if session.user_id in {"local-user", "local-studio"}
+            and not self.studio.execution_host.is_reserved_session(session.id)
         }
         grouped: dict[str, list[RunRecord]] = {}
-        for run in self.studio.event_store.list_runs():
-            if run.agent_id != agent_id:
-                continue
+        for run in self.studio.event_store.list_runs(agent_id=agent_id):
             grouped.setdefault(run.session_id, []).append(run)
         for session_id, runs in grouped.items():
             records[session_id] = self._session_record(runs)
         ordered = list(records.values())
-        ordered.sort(key=lambda item: item["UpdatedAt"], reverse=True)
+        # UpdatedAt 相同（同一秒创建的"新会话"、毫秒级并发会话）时以 SessionId
+        # 定序，避免两次 ListSessions 之间插入顺序漂移导致前端列表"乱跳"。
+        ordered.sort(
+            key=lambda item: (item["UpdatedAt"], item["SessionId"]),
+            reverse=True,
+        )
         return ordered
 
     def _session_metadata_record(self, session: Session) -> dict[str, Any]:
@@ -1197,27 +1480,39 @@ class StudioSharedWebBridge:
         binding_ids = list(draft.spec.bindings.model_profile_ids)
         if not binding_ids and draft.spec.bindings.model_profile_id:
             binding_ids = [draft.spec.bindings.model_profile_id]
-        descriptors: list[dict[str, Any]] = []
+        resolved_descriptors: list[tuple[str, dict[str, Any]]] = []
         for binding_id in binding_ids:
-            spec = self.studio.catalog.resolve_model(
-                draft.spec.bindings.model_copy(
-                    update={"model_profile_id": binding_id, "model_profile_ids": []}
+            try:
+                spec = self.studio.catalog.resolve_model(
+                    draft.spec.bindings.model_copy(
+                        update={"model_profile_id": binding_id, "model_profile_ids": []}
+                    )
                 )
-            )
+            except StudioError:
+                # provider 目录是惰性发现的；绑定指向尚未发现/已失效的
+                # model:provider:* 资源时跳过该绑定，回退到后续描述符，
+                # 而不是让整个 bootstrap 404（前端只能无限转圈）。
+                continue
             if spec is not None:
-                descriptors.append(
-                    self._model_descriptor_from_spec(
-                        draft,
-                        spec,
-                        display_name=self.studio.catalog.get(binding_id).display_name,
+                resolved_descriptors.append(
+                    (
+                        binding_id,
+                        self._model_descriptor_from_spec(
+                            draft,
+                            spec,
+                            display_name=self.studio.catalog.get(binding_id).display_name,
+                        ),
                     )
                 )
-        if descriptors:
+        if resolved_descriptors:
             default_id = draft.spec.bindings.model_profile_id
-            if default_id and default_id in binding_ids:
-                default_index = binding_ids.index(default_id)
-                descriptors.insert(0, descriptors.pop(default_index))
-            return descriptors
+            # Provider resources are discovered lazily.  Keep the resource ID
+            # paired with each successfully resolved descriptor: indexing the
+            # shortened descriptor list with the original binding position
+            # raises IndexError when an earlier binding is temporarily absent.
+            if default_id:
+                resolved_descriptors.sort(key=lambda item: item[0] != default_id)
+            return [descriptor for _, descriptor in resolved_descriptors]
         if draft.spec.model is not None:
             return [self._model_descriptor_from_spec(draft, draft.spec.model)]
         return [self._unconfigured_model_descriptor(draft)]
@@ -1310,6 +1605,44 @@ class StudioSharedWebBridge:
             )
         return selected
 
+    def _select_build_model(self, build, requested: str) -> str:
+        """Authorize execution against the immutable Build model lock."""
+
+        runtime_lock = dict(getattr(build, "runtime_lock", {}) or {})
+        allowed = [str(item) for item in runtime_lock.get("models") or [] if str(item)]
+        default = str(runtime_lock.get("model") or "").strip()
+        # Managed Codex runtime-lock.json deliberately contains only the
+        # runtime and manifest digest.  Its immutable model allowlist lives in
+        # the manifest addressed by that digest (and is revalidated by
+        # CodexRunService).  Treating the generic Bundle lock as authoritative
+        # for Codex therefore turns every cold/default turn into
+        # AGENT_MODEL_REQUIRED.  Read the same pinned manifest used to build
+        # this record; framework/Harness Builds continue to use runtime_lock.
+        agent_name = str(getattr(build, "agent_name", "") or "")
+        manifest_sha256 = str(getattr(build, "manifest_sha256", "") or "")
+        if agent_name and manifest_sha256:
+            snapshot = self.studio.codex_manifests.load(agent_name)
+            if snapshot.manifest_sha256 == manifest_sha256:
+                allowed = list(snapshot.manifest.allowed_models)
+                default = snapshot.manifest.model
+        if default and default not in allowed:
+            allowed.insert(0, default)
+        selected = requested.strip() or default
+        if not selected:
+            raise StudioError(
+                "AGENT_MODEL_REQUIRED",
+                "Build 没有绑定可运行模型",
+                status_code=422,
+            )
+        if allowed and selected not in allowed:
+            raise StudioError(
+                "MODEL_NOT_BOUND",
+                "请求模型未绑定到当前 Agent Build",
+                status_code=422,
+                details={"model": selected, "allowedModels": allowed},
+            )
+        return selected
+
     def _draft(self, agent_id: str):
         return self.studio.agent_detail(agent_id)["draft"]
 
@@ -1483,11 +1816,16 @@ class StudioSharedWebBridge:
 
     @staticmethod
     def _run_output(run: RunRecord) -> str:
+        status = run.status.value if isinstance(run.status, RunStatus) else str(run.status)
+        if status == RunStatus.FAILED.value and run.error:
+            # Progress text may end with a retry notice.  Once the run is
+            # terminal, that notice must not shadow the authoritative failure
+            # recorded by the runtime.
+            return str(run.error.get("message") or "Agent 运行失败")
         if run.output:
             return run.output
         if run.error:
             return str(run.error.get("message") or "Agent 运行失败")
-        status = run.status.value if isinstance(run.status, RunStatus) else str(run.status)
         return f"运行状态：{status}"
 
     @staticmethod
@@ -1523,5 +1861,4 @@ class StudioSharedWebBridge:
             },
         )
 
-
 __all__ = ["StudioSharedWebBridge"]