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

ksadk/conversations/runtime_persistence.py

@@ -19,7 +19,13 @@ from ksadk.conversations.runtime_constants import (
     EVENT_SCAN_PAGE_SIZE,
 )
 from ksadk.conversations.runtime_observability import _extract_deferred_tool_names
+from ksadk.runtime_context import TRUSTED_IDENTITY_METADATA_KEY, PlatformIdentityContext
 from ksadk.sessions import Session, SessionEvent, resolve_session_service
+from ksadk.sessions.invocation_identity import (
+    bind_or_validate_session_identity,
+    identity_native_user_id,
+    require_complete_platform_identity,
+)
 
 
 async def ensure_conversation_session(
@@ -28,20 +34,110 @@ async def ensure_conversation_session(
     user_id: str,
     session_id: Optional[str],
     session_service_provider: Callable[[], Any] | None = None,
+    invocation_identity: Any = None,
+    allow_agent_alias: bool = False,
 ) -> Session:
-    """确保会话存在，并在显式 session_id 冲突时做 owner 校验。"""
+    """确保会话存在，并在读取历史前校验可信业务 owner。"""
     service = (session_service_provider or resolve_session_service)()
+    identity = require_complete_platform_identity(invocation_identity)
     if session_id:
-        existing = await service.get_session(session_id)
+        # Ownership is decided from metadata/state before any transcript read.
+        existing = await service.get_session_metadata(session_id)
         if existing:
-            if existing.agent_id != agent_id or existing.user_id != user_id:
-                raise HTTPException(
-                    status_code=409,
-                    detail="Session id belongs to a different agent or user",
+            if existing.agent_id != agent_id:
+                if allow_agent_alias and not identity.is_empty:
+                    # Hosted workers receive an internal instance alias while
+                    # the control plane persists the public AgentId. The
+                    # worker is already scoped to this session store; adopt
+                    # the persisted owner before validating business identity.
+                    agent_id = existing.agent_id
+                elif not identity.is_empty:
+                    raise HTTPException(status_code=404, detail="Session not found")
+                else:
+                    raise HTTPException(
+                        status_code=409,
+                        detail="Session id belongs to a different agent or user",
+                    )
+            if existing.agent_id == agent_id:
+                return await bind_or_validate_session_identity(
+                    service=service,
+                    session=existing,
+                    identity=identity,
+                    requested_user_id=user_id,
                 )
-            return existing
-        return await service.create_session(agent_id, user_id, session_id=session_id)
-    return await service.create_session(agent_id, user_id)
+        native_user_id = identity_native_user_id(identity) or user_id
+        created = await service.create_session(agent_id, native_user_id, session_id=session_id)
+        if created.agent_id != agent_id:
+            raise HTTPException(status_code=404, detail="Session not found")
+        return await bind_or_validate_session_identity(
+            service=service,
+            session=created,
+            identity=identity,
+            requested_user_id=user_id,
+        )
+    native_user_id = identity_native_user_id(identity) or user_id
+    created = await service.create_session(agent_id, native_user_id)
+    return await bind_or_validate_session_identity(
+        service=service,
+        session=created,
+        identity=identity,
+        requested_user_id=user_id,
+    )
+
+
+async def require_conversation_session(
+    *,
+    agent_id: str,
+    user_id: str,
+    session_id: str,
+    session_service_provider: Callable[[], Any] | None = None,
+    invocation_identity: Any = None,
+) -> Session:
+    """Authorize an existing session without creating state on a read/control path."""
+
+    service = (session_service_provider or resolve_session_service)()
+    identity = require_complete_platform_identity(invocation_identity)
+    existing = await service.get_session_metadata(session_id)
+    if existing is None:
+        raise HTTPException(status_code=404, detail="Session not found")
+    if existing.agent_id != agent_id:
+        if not identity.is_empty:
+            raise HTTPException(status_code=404, detail="Session not found")
+        raise HTTPException(
+            status_code=409,
+            detail="Session id belongs to a different agent or user",
+        )
+    return await bind_or_validate_session_identity(
+        service=service,
+        session=existing,
+        identity=identity,
+        requested_user_id=user_id,
+    )
+
+
+async def prepare_stream_identity_session(
+    *,
+    agent_id: str,
+    user_id: str,
+    session_id: str | None,
+    request_metadata: Mapping[str, Any] | None,
+    session_service_provider: Callable[[], Any] | None = None,
+) -> tuple[str, str | None, PlatformIdentityContext, dict[str, Any]]:
+    """Authorize a stream before preview reads and hide its private identity carrier."""
+
+    public_metadata = dict(request_metadata or {})
+    identity_payload = public_metadata.pop(TRUSTED_IDENTITY_METADATA_KEY, None)
+    identity = PlatformIdentityContext.from_payload(identity_payload)
+    if not identity_payload:
+        return user_id, session_id, identity, public_metadata
+    session = await ensure_conversation_session(
+        agent_id=agent_id,
+        user_id=user_id,
+        session_id=session_id,
+        session_service_provider=session_service_provider,
+        invocation_identity=identity_payload,
+    )
+    return session.user_id, session.id, identity, public_metadata
 
 
 async def append_conversation_event(

ksadk/conversations/runtime_preparation.py

@@ -49,6 +49,7 @@ from ksadk.conversations.runtime_metadata import (
 )
 from ksadk.conversations.runtime_observability import _latest_deferred_tool_names
 from ksadk.conversations.runtime_payloads import PreparedConversationTurn
+from ksadk.session_context import split_session_context
 from ksadk.conversations.runtime_persistence import (
     append_conversation_event,
     append_run_resume_event,
@@ -72,6 +73,8 @@ from ksadk.conversations.runtime_resume import (
 )
 from ksadk.ids import new_run_id
 from ksadk.model_policy import model_policy_options_for_model
+from ksadk.runtime_context import TRUSTED_IDENTITY_METADATA_KEY, PlatformIdentityContext
+from ksadk.session_context import split_session_context
 from ksadk.sessions import SessionEvent, resolve_session_service
 
 logger = logging.getLogger(__name__)
@@ -110,6 +113,7 @@ async def build_run_input(
     deployment_mode: str = "local",
     agent_max_input_tokens: int | None = None,
     agent_reserve_output_tokens: int | None = None,
+    resume_lifecycle_prepared: bool = False,
 ) -> PreparedConversationTurn:
     """构建一次 turn 的标准运行输入，并在进入模型前做上下文投影/压缩。
 
@@ -120,25 +124,25 @@ async def build_run_input(
     caller_run_trigger = trigger_from_resume_input(resume_input)
     provider = session_service_provider or resolve_session_service
     service = provider()
-    resolved_user_id = user_id
-    if session_id:
-        existing_session = await service.get_session(session_id)
-        if existing_session and existing_session.user_id:
-            resolved_user_id = existing_session.user_id
+    private_request_metadata = dict(request_metadata or {})
+    identity_payload = private_request_metadata.pop(TRUSTED_IDENTITY_METADATA_KEY, None)
+    invocation_identity = PlatformIdentityContext.from_payload(identity_payload)
 
     session = await ensure_conversation_session(
         agent_id=agent_id,
-        user_id=resolved_user_id,
+        user_id=user_id,
         session_id=session_id,
         session_service_provider=provider,
+        invocation_identity=invocation_identity,
     )
+    resolved_user_id = session.user_id
     resolved_session_id = session.id
     resolved_invocation_id = str(invocation_id or new_run_id(resolved_session_id))
     resolved_model_metadata = await _resolve_runtime_model_metadata(
         model,
         model_metadata=model_metadata,
     )
-    normalized_request_metadata = dict(request_metadata or {})
+    session_context, normalized_request_metadata = split_session_context(private_request_metadata)
     normalized_custom_metadata = dict(custom_metadata or {})
     policy_model = model or os.getenv("OPENAI_MODEL_NAME") or os.getenv("MODEL_NAME")
     normalized_model_options = {
@@ -170,41 +174,41 @@ async def build_run_input(
     if resume_input is not None:
         if not session_id:
             raise ValueError("Responses resume input requires session_id")
-        existing_events = await service.get_events(resolved_session_id)
         normalized_resume_input = dict(resume_input)
         if _is_checkpoint_resume_input(normalized_resume_input):
             normalized_resume_input = _normalize_checkpoint_resume_input(normalized_resume_input)
-            await append_run_resume_event(
-                session_id=resolved_session_id,
-                author=agent_id,
-                run_id=str(normalized_resume_input["run_id"]),
-                checkpoint_id=str(normalized_resume_input["checkpoint_id"]),
-                resume_attempt_id=str(normalized_resume_input["resume_attempt_id"]),
-                framework=str(normalized_resume_input["framework"]),
-                framework_ref=normalized_resume_input["framework_ref"],
-                invocation_id=resolved_invocation_id,
-                session_service_provider=provider,
-            )
-            # 补写 run_status(resuming)：让 ActiveRunStatus 在 resume 期间正确反映"恢复中"。
-            # append_run_resume_event 写的是 run_resume 事件（status=resuming），而
-            # _latest_session_run_status 只扫 run_status 事件 → 不补写则
-            # resuming 不进 ActiveRunStatus。
-            await append_run_status_event(
-                session_id=resolved_session_id,
-                author=agent_id,
-                status="resuming",
-                invocation_id=resolved_invocation_id,
-                detail="checkpoint_resume",
-                session_service_provider=provider,
-                run_mode=caller_run_mode,
-                run_trigger=RUN_TRIGGER_CHECKPOINT_RESUME,
-            )
+            if not resume_lifecycle_prepared:
+                await append_run_resume_event(
+                    session_id=resolved_session_id,
+                    author=agent_id,
+                    run_id=str(normalized_resume_input["run_id"]),
+                    checkpoint_id=str(normalized_resume_input["checkpoint_id"]),
+                    resume_attempt_id=str(normalized_resume_input["resume_attempt_id"]),
+                    framework=str(normalized_resume_input["framework"]),
+                    framework_ref=normalized_resume_input["framework_ref"],
+                    invocation_id=resolved_invocation_id,
+                    session_service_provider=provider,
+                )
+                # run_resume 与 ActiveRunStatus 分属不同事件类型，因此补写 resuming。
+                await append_run_status_event(
+                    session_id=resolved_session_id,
+                    author=agent_id,
+                    status="resuming",
+                    invocation_id=resolved_invocation_id,
+                    detail="checkpoint_resume",
+                    session_service_provider=provider,
+                    run_mode=caller_run_mode,
+                    run_trigger=RUN_TRIGGER_CHECKPOINT_RESUME,
+                )
             event_history = await service.get_events(resolved_session_id)
             history = build_history_from_events(event_history)
             responses_history = project_responses_history(event_history)
             return PreparedConversationTurn(
+                session_context=session_context.to_payload(),
                 session_id=resolved_session_id,
                 invocation_id=resolved_invocation_id,
+                user_id=resolved_user_id,
+                agent_id=agent_id,
                 user_input="",
                 user_display_input="",
                 history=history,
@@ -239,6 +243,7 @@ async def build_run_input(
                 provider_ref=provider_ref,
             )
 
+        existing_events = await service.get_events(resolved_session_id)
         is_approval_resume = _is_approval_resume_input(normalized_resume_input)
         existing_tool_receipt_event = None
         if is_approval_resume and not _has_pending_approval(existing_events):
@@ -319,8 +324,11 @@ async def build_run_input(
         history = build_history_from_events(event_history)
         responses_history = project_responses_history(event_history)
         return PreparedConversationTurn(
+            session_context=session_context.to_payload(),
             session_id=resolved_session_id,
             invocation_id=resolved_invocation_id,
+            user_id=resolved_user_id,
+            agent_id=agent_id,
             user_input=resume_text,
             user_display_input=resume_text,
             history=history,
@@ -478,6 +486,7 @@ async def build_run_input(
         working_state = _latest_checkpoint_working_state(event_history)
 
     prepared = PreparedConversationTurn(
+        session_context=session_context.to_payload(),
         session_id=resolved_session_id,
         invocation_id=resolved_invocation_id,
         user_id=resolved_user_id,

ksadk/conversations/runtime_resume.py

@@ -185,6 +185,48 @@ def _parse_approval_arguments(value: Any) -> dict[str, Any]:
 
 
 def _approval_decision_from_resume(resume_input: Mapping[str, Any]) -> dict[str, Any]:
+    # ksadk_resume + decisions 协议（HumanInTheLoopMiddleware）：
+    # resume_input.value.decisions[0].type 为 approve/edit/reject。
+    value = resume_input.get("value")
+    if isinstance(value, Mapping):
+        decisions = value.get("decisions")
+        if isinstance(decisions, list) and decisions:
+            first = decisions[0]
+            if isinstance(first, Mapping):
+                decision_type = str(first.get("type") or "").strip().lower()
+                if decision_type in {"approve", "edit"}:
+                    approved = True
+                    if decision_type == "edit":
+                        # edit 带修改后的参数；记录到 decision 供下游使用。
+                        edited = first.get("edited_action")
+                        if isinstance(edited, Mapping):
+                            return {
+                                "approved": True,
+                                "approval_request_id": str(
+                                    resume_input.get("approval_request_id")
+                                    or resume_input.get("interrupt_id")
+                                    or resume_input.get("id")
+                                    or ""
+                                ),
+                                "edited_action": dict(edited),
+                            }
+                elif decision_type in {"reject", "respond"}:
+                    approved = False
+                else:
+                    approved = True
+                decision = {
+                    "approved": approved,
+                    "approval_request_id": str(
+                        resume_input.get("approval_request_id")
+                        or resume_input.get("interrupt_id")
+                        or resume_input.get("id")
+                        or ""
+                    ),
+                }
+                message = first.get("message") or first.get("feedback")
+                if message is not None:
+                    decision["reason"] = str(message)
+                return decision
     if "approve" in resume_input:
         approved = bool(resume_input.get("approve"))
     elif "approved" in resume_input:
@@ -624,7 +666,11 @@ def _extract_agentengine_metadata(result: Mapping[str, Any] | None) -> dict[str,
     agentengine = metadata.get("agentengine")
     if not isinstance(agentengine, Mapping):
         return {}
-    return {"agentengine": dict(agentengine)}
+    return {
+        "agentengine": {
+            key: value for key, value in agentengine.items() if key != "session_context"
+        }
+    }
 
 
 def _checkpoint_event_args_from_agentengine_metadata(
@@ -682,7 +728,9 @@ def _merge_agentengine_metadata(
         agentengine = metadata.get("agentengine")
         if not isinstance(agentengine, Mapping):
             continue
-        next_agentengine = dict(agentengine)
+        next_agentengine = {
+            key: value for key, value in agentengine.items() if key != "session_context"
+        }
         merged.update(next_agentengine)
         framework_ref = agentengine.get("framework_ref")
         if isinstance(framework_ref, Mapping):

ksadk/conversations/runtime_stream_events.py

@@ -10,6 +10,7 @@ from ksadk.conversations.run_kinds import (
     trigger_from_resume_input,
     validate_run_mode,
 )
+from ksadk.conversations.runtime_baseline import record_baseline_turn
 from ksadk.conversations.runtime_compaction import preview_auto_compaction
 from ksadk.conversations.runtime_constants import (
     ASSISTANT_STREAM_SNAPSHOT_INTERVAL_SECONDS,
@@ -46,6 +47,7 @@ from ksadk.conversations.runtime_observability import (
     _set_conversation_usage_attributes,
     _set_prompt_cache_attributes,
     _set_prompt_source_attributes,
+    _set_skill_eval_result_attributes,
     _set_span_attribute,
     _span_current_context,
     _span_feedback_metadata,
@@ -57,6 +59,7 @@ from ksadk.conversations.runtime_persistence import (
     append_reasoning_event,
     append_run_checkpoint_event,
     append_run_status_event,
+    prepare_stream_identity_session,
 )
 from ksadk.conversations.runtime_preparation import _refresh_history, build_run_input
 from ksadk.conversations.runtime_resume import (
@@ -72,6 +75,7 @@ from ksadk.conversations.runtime_resume import (
     _tool_receipt_metadata,
 )
 from ksadk.model_policy import fallback_model_for_exception, model_policy_options_for_model
+from ksadk.runtime.skill_eval_result import skill_eval_response_fields
 from ksadk.runtime_context import (
     PlatformInvocationContext,
     platform_invocation_scope,
@@ -83,35 +87,6 @@ from ksadk.tools.gateway import (
 )
 
 
-def _record_baseline_turn(
-    *,
-    prepared: Any,
-    model: str | None,
-    usage: Any,
-    ptl: bool,
-    attempts: int,
-    turn_start_monotonic: float | None,
-) -> None:
-    """env-gated 旁路采集：未启用时 no-op，启用时记录一条 turn 基线。不进决策路径。"""
-    from ksadk.context_engine.baseline import record_baseline_turn
-
-    latency_ms = None
-    if turn_start_monotonic is not None:
-        latency_ms = int((time.monotonic() - turn_start_monotonic) * 1000)
-    record_baseline_turn(
-        getattr(prepared, "shadow_context_plan", None),
-        session_id=getattr(prepared, "session_id", ""),
-        invocation_id=getattr(prepared, "invocation_id", ""),
-        model=str(model or ""),
-        usage=usage if isinstance(usage, Mapping) else None,
-        compaction_triggered=bool(getattr(prepared, "compaction_triggered", False)),
-        compaction_trigger=str(getattr(prepared, "compaction_trigger", "") or ""),
-        prompt_too_long=ptl,
-        retry_attempts=attempts,
-        turn_latency_ms=latency_ms,
-    )
-
-
 async def _iter_conversation_turn_events(
     *,
     runner: Any,
@@ -136,6 +111,7 @@ async def _iter_conversation_turn_events(
     agent_system: str = "",
     agent_task: str = "",
     prompt_integration_mode: str = "",
+    resume_lifecycle_prepared: bool = False,
 ) -> AsyncIterator[dict[str, Any]]:
     """Internal semantic event stream shared by protocol serializers."""
     provider = session_service_provider or resolve_session_service
@@ -144,6 +120,18 @@ async def _iter_conversation_turn_events(
     _governance_record_turn_start(governance)
     entry_run_mode = validate_run_mode(run_mode)
     entry_run_trigger = trigger_from_resume_input(resume_input)
+    (
+        user_id,
+        session_id,
+        invocation_identity,
+        public_request_metadata,
+    ) = await prepare_stream_identity_session(
+        agent_id=agent_id,
+        user_id=user_id,
+        session_id=session_id,
+        request_metadata=request_metadata,
+        session_service_provider=provider,
+    )
     if resume_input is None:
         compaction_preview = await preview_auto_compaction(
             agent_id=agent_id,
@@ -198,6 +186,7 @@ async def _iter_conversation_turn_events(
             agent_system=agent_system,
             agent_task=agent_task,
             prompt_integration_mode=prompt_integration_mode,
+            resume_lifecycle_prepared=resume_lifecycle_prepared,
         )
         # prepared 之后的 run_status 写入复用 prepared 的 mode/trigger
         run_mode = prepared.run_mode
@@ -218,15 +207,19 @@ async def _iter_conversation_turn_events(
         yield {"type": "error", "message": str(exc) or "Agent 运行失败"}
         return
     _inject_runner_deferred_tools_for_request(runner, prepared)
+    effective_user_id = prepared.user_id or user_id
     ambient_contexts = _build_runner_ambient_contexts(
         runner=runner,
-        user_id=user_id,
+        user_id=effective_user_id,
         user_input=prepared.user_input,
     )
     prepared.memory_recall_events = ambient_contexts.get("memory_recall_events", [])
+    from ksadk.session_context import SessionContext
+
     runtime_context = PlatformInvocationContext(
+        session=SessionContext.from_payload(prepared.session_context),
         agent_id=agent_id,
-        user_id=user_id,
+        user_id=effective_user_id,
         account_id=str(account_id or ""),
         session_id=prepared.session_id,
         history=list(prepared.history),
@@ -245,6 +238,7 @@ async def _iter_conversation_turn_events(
         kb_context=ambient_contexts.get("kb_context"),
         memory_context=ambient_contexts.get("memory_context"),
         tool_approval_mode=str(prepared.request_metadata.get("tool_approval_mode") or ""),
+        identity=invocation_identity,
     )
     if prepared.compaction_triggered:
         yield {
@@ -288,7 +282,7 @@ async def _iter_conversation_turn_events(
         _set_conversation_span_attributes(
             span,
             agent_id=agent_id,
-            user_id=user_id,
+            user_id=effective_user_id,
             session_id=prepared.session_id,
             invocation_id=prepared.invocation_id,
             runner_name=runner_name,
@@ -304,7 +298,7 @@ async def _iter_conversation_turn_events(
         yield {
             "type": "started",
             "session_id": prepared.session_id,
-            "metadata": {**trace_metadata, **dict(request_metadata or {})},
+            "metadata": {**trace_metadata, **public_request_metadata},
         }
         await append_run_status_event(
             session_id=prepared.session_id,
@@ -324,6 +318,7 @@ async def _iter_conversation_turn_events(
         emitted_anything = False
         emitted_response_artifacts = False
         saw_final_chunk = False
+        result_fields: dict[str, Any] = {}
         responses_output: list[Any] = []
         responses_response_id: str | None = response_id
         runner_agentengine_metadata: dict[str, Any] = {}
@@ -751,6 +746,9 @@ async def _iter_conversation_turn_events(
                                 return
                             if chunk_type == "final":
                                 saw_final_chunk = True
+                                result_fields = skill_eval_response_fields(chunk)
+                                if result_fields:
+                                    _set_skill_eval_result_attributes(span, result_fields["skill_eval_result"])
                                 final_text = str(chunk.get("output", ""))
                                 if final_text:
                                     accumulated_text = final_text
@@ -941,7 +939,7 @@ async def _iter_conversation_turn_events(
         )
         await _auto_save_ltm_turn(
             agent_id=agent_id,
-            user_id=user_id,
+            user_id=effective_user_id,
             prepared=prepared,
             output_text=accumulated_text,
             runner_type=runtime_context.runner_type,
@@ -964,7 +962,7 @@ async def _iter_conversation_turn_events(
             usage=assistant_metadata.get("usage"),
         )
         _set_prompt_source_attributes(span, getattr(prepared, "compiled_prompt", None))
-        _record_baseline_turn(
+        record_baseline_turn(
             prepared=prepared,
             model=model,
             usage=assistant_metadata.get("usage"),
@@ -975,6 +973,7 @@ async def _iter_conversation_turn_events(
         _finish_span()
         yield {
             "type": "completed",
+            **result_fields,
             "output_text": accumulated_text,
             "model": model,
             "session_id": prepared.session_id,