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

ksadk/conversations/runtime_preparation.py

@@ -1,13 +1,19 @@
 from __future__ import annotations
 
+import logging
 import os
 from typing import Any, Callable, Dict, Mapping, Optional, Sequence
 
+from ksadk.context_engine.shadow_plan import (
+    build_shadow_context_plan_dict,
+    minimal_shadow_context_plan_dict,
+)
 from ksadk.conversations.attachments import compact_attachment_result_for_session
 from ksadk.conversations.context import (
     build_history_from_events,
     build_request_history,
     build_responses_history_from_messages,
+    canonical_event_type,
     project_responses_history,
 )
 from ksadk.conversations.model_options import normalize_model_options
@@ -66,7 +72,9 @@ 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.sessions import resolve_session_service
+from ksadk.sessions import SessionEvent, resolve_session_service
+
+logger = logging.getLogger(__name__)
 
 
 async def build_run_input(
@@ -87,6 +95,21 @@ async def build_run_input(
     governance_state: RuntimeGovernanceState | None = None,
     session_service_provider: Callable[[], Any] | None = None,
     run_mode: str = RUN_MODE_FOREGROUND,
+    runner: Any | None = None,
+    runtime_type: str | None = None,
+    agent_system: str = "",
+    agent_task: str = "",
+    prompt_integration_mode: str = "",
+    context_engine_rollout: str | None = None,
+    memory_recall_enabled: bool | None = None,
+    memory_write_rollout: str | None = None,
+    memory_enabled: bool | None = None,
+    memory_write_mode: str = "candidate",
+    flush_before_compaction: bool = True,
+    provider_ref: str = "local-default",
+    deployment_mode: str = "local",
+    agent_max_input_tokens: int | None = None,
+    agent_reserve_output_tokens: int | None = None,
 ) -> PreparedConversationTurn:
     """构建一次 turn 的标准运行输入，并在进入模型前做上下文投影/压缩。
 
@@ -124,6 +147,26 @@ async def build_run_input(
     }
     normalized_instructions = str(instructions or "").strip()
 
+    # PR A：当 agent_system/agent_task 非空时，编译真实 CompiledPrompt（含 stable section）。
+    # 仅用于 hash/trace/future projection，不改 Runner 输入（payload["instructions"] 不变）。
+    # platform_policy_source 默认 EnvPlatformPolicySource（env 未设→不产 platform_safety）。
+    compiled_prompt: dict[str, Any] | None = None
+    if (agent_system or "").strip() or (agent_task or "").strip():
+        from ksadk.prompts.resolved import (
+            ResolvedPromptSources,
+            compile_resolved_prompt_dict,
+            get_default_platform_policy_source,
+        )
+
+        compiled_prompt = compile_resolved_prompt_dict(
+            ResolvedPromptSources(
+                agent_system=agent_system,
+                agent_task=agent_task,
+                request_instructions=normalized_instructions,
+                platform_policy_source=get_default_platform_policy_source(),
+            )
+        )
+
     if resume_input is not None:
         if not session_id:
             raise ValueError("Responses resume input requires session_id")
@@ -184,6 +227,16 @@ async def build_run_input(
                 resume_input=normalized_resume_input,
                 run_mode=caller_run_mode,
                 run_trigger=RUN_TRIGGER_CHECKPOINT_RESUME,
+                shadow_context_plan=minimal_shadow_context_plan_dict(
+                    runner=runner, runtime_type=runtime_type, deployment_mode=deployment_mode
+                ),
+                compiled_prompt=None,
+                memory_write_rollout=memory_write_rollout,
+                memory_enabled=memory_enabled,
+                memory_recall_enabled=memory_recall_enabled,
+                memory_write_mode=memory_write_mode,
+                flush_before_compaction=flush_before_compaction,
+                provider_ref=provider_ref,
             )
 
         is_approval_resume = _is_approval_resume_input(normalized_resume_input)
@@ -253,6 +306,14 @@ async def build_run_input(
                 existing_events=existing_events,
             )
         effective_resume_input = tool_resume_input or normalized_resume_input
+        if tool_resume_input is not None:
+            # ToolGateway approvals complete after an otherwise normal tool
+            # call. Only LangGraph needs this private marker to restart a
+            # terminal graph semantically; runtime_input strips it elsewhere.
+            effective_resume_input = {
+                **tool_resume_input,
+                "_ksadk_gateway_approval_resume": True,
+            }
         del existing_events
         event_history = await service.get_events(resolved_session_id)
         history = build_history_from_events(event_history)
@@ -279,6 +340,23 @@ async def build_run_input(
             resume_input=effective_resume_input,
             run_mode=caller_run_mode,
             run_trigger=RUN_TRIGGER_APPROVAL_RESUME,
+            shadow_context_plan=build_shadow_context_plan_dict(
+                instructions=normalized_instructions,
+                history=history,
+                user_input=resume_text,
+                request_metadata=normalized_request_metadata,
+                runner=runner,
+                runtime_type=runtime_type,
+                model_metadata=resolved_model_metadata,
+                deployment_mode=deployment_mode,
+            ),
+            compiled_prompt=None,
+            memory_write_rollout=memory_write_rollout,
+            memory_enabled=memory_enabled,
+            memory_recall_enabled=memory_recall_enabled,
+            memory_write_mode=memory_write_mode,
+            flush_before_compaction=flush_before_compaction,
+            provider_ref=provider_ref,
         )
 
     normalized_messages = _normalized_conversation_messages(messages)
@@ -341,6 +419,17 @@ async def build_run_input(
         user_input=user_input or user_display_input,
     )
 
+    # compaction_owner 硬门控（方案 §6.2）：从 capability 取 owner，非 ksadk 时不走双阈值
+    from ksadk.context_engine.capabilities import (
+        capabilities_for_runner,
+        capabilities_for_runtime_type,
+    )
+
+    _caps = (
+        capabilities_for_runner(runner)
+        if runner is not None
+        else capabilities_for_runtime_type(runtime_type)
+    )
     checkpoint = await _compact_conversation_history_with_governance(
         governance_state,
         session_id=resolved_session_id,
@@ -349,6 +438,9 @@ async def build_run_input(
         model=model,
         model_metadata=resolved_model_metadata,
         session_service_provider=provider,
+        # PR D1：双阈值门控透传。ksadk_hosted → soft/hard proactive compact；否则旧单阈值。
+        prompt_integration_mode=prompt_integration_mode,
+        compaction_owner=_caps.compaction_owner,
     )
     event_history = await service.get_events(resolved_session_id)
     history = build_history_from_events(event_history)
@@ -364,10 +456,32 @@ async def build_run_input(
         request_responses_history,
         responses_history,
     )
+    # The current user event is persisted before context construction so an
+    # interrupted turn remains auditable.  That event belongs to
+    # ``current_input`` though, not to prior history.  Keep the legacy
+    # ``prepared.history`` contract unchanged for non-hosted paths, while the
+    # KsADK-owned planner receives only events from earlier invocations.  Using
+    # invocation_id (instead of text equality) also handles users deliberately
+    # repeating the same message across turns.
+    hosted_history = _merge_request_history_with_session_history(
+        request_history,
+        build_history_from_events(
+            [event for event in event_history if event.invocation_id != resolved_invocation_id]
+        ),
+    )
+    # PR D2：取最新 checkpoint 的 WorkingState（仅 ksadk_hosted 路径重注入）。
+    # 非 ksadk_hosted → working_state=None（零注入，Runner 输入与旧逻辑一致）。
+    # PTL retry 后 _refresh_history 也会重读 events，但此处 build_run_input 首次构建时取一次即可；
+    # PTL 路径若产生新 checkpoint，retry 用 prepared 已有 working_state（保守：不中途换）。
+    working_state: dict[str, Any] | None = None
+    if prompt_integration_mode == "ksadk_hosted":
+        working_state = _latest_checkpoint_working_state(event_history)
 
-    return PreparedConversationTurn(
+    prepared = PreparedConversationTurn(
         session_id=resolved_session_id,
         invocation_id=resolved_invocation_id,
+        user_id=resolved_user_id,
+        agent_id=agent_id,
         user_input=user_input,
         user_display_input=user_display_input or user_input,
         history=history,
@@ -397,7 +511,171 @@ async def build_run_input(
         ),
         run_mode=caller_run_mode,
         run_trigger=caller_run_trigger,
+        shadow_context_plan=build_shadow_context_plan_dict(
+            instructions=normalized_instructions,
+            history=hosted_history if prompt_integration_mode == "ksadk_hosted" else history,
+            user_input=user_input,
+            request_metadata=normalized_request_metadata,
+            runner=runner,
+            runtime_type=runtime_type,
+            model_metadata=resolved_model_metadata,
+            prompt_shadow=compiled_prompt,
+            prompt_integration_mode=prompt_integration_mode,
+            deployment_mode=deployment_mode,
+        ),
+        compiled_prompt=compiled_prompt,
+        prompt_integration_mode=prompt_integration_mode,
+        working_state=working_state,
+        memory_write_rollout=memory_write_rollout,
+        memory_enabled=memory_enabled,
+        memory_recall_enabled=memory_recall_enabled,
+        memory_write_mode=memory_write_mode,
+        flush_before_compaction=flush_before_compaction,
+        provider_ref=provider_ref,
+    )
+    # PR E：ksadk_hosted + V2 开关时运行真实 hosted 链路，回填 context_plan/assembled_input。
+    # 失败回退空字段（prepared 字段语义完整），不阻断主链路。
+    await _maybe_fill_hosted_pipeline(
+        prepared,
+        compiled_prompt=compiled_prompt,
+        user_input=user_input,
+        history=hosted_history,
+        working_state=working_state,
+        model_metadata=resolved_model_metadata,
+        prompt_integration_mode=prompt_integration_mode,
+        context_engine_rollout=context_engine_rollout,
+        memory_recall_enabled=memory_recall_enabled,
+        runtime_type=runtime_type,
+        session_id=resolved_session_id,
+        invocation_id=resolved_invocation_id,
+        user_id=resolved_user_id,
+        agent_id=agent_id,
+        agent_max_input_tokens=agent_max_input_tokens,
+        agent_reserve_output_tokens=agent_reserve_output_tokens,
+    )
+    return prepared
+
+
+async def _maybe_fill_hosted_pipeline(
+    prepared: PreparedConversationTurn,
+    *,
+    compiled_prompt: dict[str, Any] | None,
+    user_input: str,
+    history: list[dict[str, str]],
+    working_state: dict[str, Any] | None,
+    model_metadata: dict[str, Any],
+    prompt_integration_mode: str,
+    context_engine_rollout: str | None,
+    memory_recall_enabled: bool | None,
+    agent_max_input_tokens: int | None = None,
+    agent_reserve_output_tokens: int | None = None,
+    runtime_type: str | None,
+    session_id: str,
+    invocation_id: str,
+    user_id: str,
+    agent_id: str,
+) -> None:
+    """PR E：在 ksadk_hosted + V2 时运行 hosted 链路并回填 plan/assembly。
+
+    门控三重：``KSADK_CONTEXT_ENGINE_V2_ENABLED`` × ``prompt_integration_mode=="ksadk_hosted"``
+    × 已编译出含 prompt_content 的 CompiledPrompt（agent_system/agent_task 非空）。任一不满足
+    → 不回填（走旧 PR B 分支，字节级一致）。
+
+    仅对 ``prompt_owner=ksadk`` 的 runtime（langgraph 系）启用；native_runtime（codex）不进入，
+    保证 Managed Codex 不被接管（方案 §6.2 / PCM-RUNNER-003）。
+    """
+    from ksadk.context_engine.capabilities import (
+        assert_capability_not_circuit_open,
+        capabilities_for_runtime_type,
     )
+    from ksadk.context_engine.hosted_pipeline import (
+        default_hosted_contributors,
+        hosted_pipeline_enabled,
+        run_hosted_pipeline,
+    )
+
+    if (
+        not hosted_pipeline_enabled(rollout=context_engine_rollout)
+        or prompt_integration_mode != "ksadk_hosted"
+    ):
+        return
+    if (
+        not isinstance(compiled_prompt, dict)
+        or not str(compiled_prompt.get("prompt_content") or "").strip()
+    ):
+        return
+    caps = capabilities_for_runtime_type(runtime_type)
+    if caps.prompt_owner != "ksadk":
+        return
+    # 门禁：该 Runner 若已因 capability mismatch 熔断，回退旧路径（方案 §6.1）。不抛给主链路。
+    try:
+        assert_capability_not_circuit_open(runtime_type=runtime_type, label="hosted_pipeline")
+    except Exception:  # noqa: BLE001
+        logger.info("hosted pipeline skipped for session=%s: capability circuit open", session_id)
+        return
+    # PR E：注入默认 Contributors（MemoryRecall 等）进真实链路（方案 §8.7）。
+    contributors = default_hosted_contributors(
+        user_id=user_id,
+        agent_id=agent_id,
+        memory_recall_enabled=memory_recall_enabled,
+    )
+    try:
+        result = await run_hosted_pipeline(
+            compiled_prompt=compiled_prompt,
+            user_input=user_input,
+            history=history,
+            working_state=working_state,
+            model_metadata=model_metadata,
+            contributors=contributors,
+            # 与 shadow_plan 口径一致：ksadk_hosted + prompt_owner=ksadk + langgraph → ksadk_hosted
+            integration_mode=(
+                "ksadk_hosted"
+                if prompt_integration_mode == "ksadk_hosted"
+                and caps.prompt_owner == "ksadk"
+                and runtime_type == "langgraph"
+                else caps.integration_mode
+            ),
+            accounting_accuracy=caps.token_accounting,
+            session_id=session_id,
+            invocation_id=invocation_id,
+            user_id=user_id,
+            agent_id=agent_id,
+            agent_max_input_tokens=agent_max_input_tokens,
+            agent_reserve_output_tokens=agent_reserve_output_tokens,
+        )
+    except Exception:  # noqa: BLE001
+        logger.warning(
+            "hosted pipeline failed for session=%s; falling back to PR B path",
+            session_id,
+        )
+        return
+    if result is None:
+        return
+    prepared.context_plan = result.plan
+    prepared.assembled_input = {
+        "format": result.assembled.format,
+        "system": result.assembled.system,
+        "messages": list(result.assembled.messages),
+        "estimated_tokens": result.assembled.estimated_tokens,
+        "warnings": list(result.assembled.warnings),
+    }
+
+
+def _latest_checkpoint_working_state(events: Sequence[SessionEvent]) -> dict[str, Any] | None:
+    """取最新 context_checkpoint 事件的 working_state（PR D2）。
+
+    checkpoint metadata 由 compact_conversation_history 写入（仅 ksadk_hosted）。
+    无 checkpoint 或无 working_state 键时返回 None。
+    """
+    for event in reversed(list(events)):
+        if canonical_event_type(event.event_type) != "context_checkpoint":
+            continue
+        meta = event.metadata or {}
+        ws = meta.get("working_state")
+        if isinstance(ws, dict):
+            return ws
+        return None
+    return None
 
 
 async def _refresh_history(

ksadk/conversations/runtime_resume.py

@@ -15,6 +15,7 @@ from ksadk.conversations.run_kinds import (
     validate_run_mode,
 )
 from ksadk.conversations.runtime_persistence import append_conversation_event
+from ksadk.events.v1_compat import EventTypeV1 as EventType
 from ksadk.sessions import SessionEvent
 from ksadk.tools.gateway import (
     build_tool_receipt_idempotency_key,
@@ -24,11 +25,7 @@ from ksadk.tools.gateway import (
 def _has_pending_approval(events: Sequence[SessionEvent]) -> bool:
     pending = 0
     for event in events:
-        event_type = canonical_event_type(
-            event.event_type,
-            author=event.author,
-            role=str((event.content or {}).get("role") or ""),
-        )
+        event_type = _approval_lifecycle_event_type(event)
         if event_type == "approval_request":
             pending += 1
         elif event_type == "approval_response" and pending > 0:
@@ -37,23 +34,17 @@ def _has_pending_approval(events: Sequence[SessionEvent]) -> bool:
 
 
 def _approval_request_id_from_event(event: SessionEvent) -> str:
-    metadata = event.metadata or {}
-    interrupt_info = metadata.get("interrupt_info")
-    if isinstance(interrupt_info, Mapping):
-        value = interrupt_info.get("approval_request_id") or interrupt_info.get("id")
-        if value:
-            return str(value)
+    interrupt_info = _approval_interrupt_info_from_event(event)
+    value = interrupt_info.get("approval_request_id") or interrupt_info.get("id")
+    if value:
+        return str(value)
     return str(event.id or "")
 
 
 def _pending_approval_events(events: Sequence[SessionEvent]) -> list[SessionEvent]:
     pending: list[SessionEvent] = []
     for event in events:
-        event_type = canonical_event_type(
-            event.event_type,
-            author=event.author,
-            role=str((event.content or {}).get("role") or ""),
-        )
+        event_type = _approval_lifecycle_event_type(event)
         if event_type == "approval_request":
             pending.append(event)
             continue
@@ -79,17 +70,71 @@ def _pending_approval_events(events: Sequence[SessionEvent]) -> list[SessionEven
 
 def _approval_request_events(events: Sequence[SessionEvent]) -> list[SessionEvent]:
     return [
-        event
-        for event in events
-        if canonical_event_type(
-            event.event_type,
-            author=event.author,
-            role=str((event.content or {}).get("role") or ""),
-        )
-        == "approval_request"
+        event for event in events if _approval_lifecycle_event_type(event) == "approval_request"
     ]
 
 
+def _approval_lifecycle_event_type(event: SessionEvent) -> str:
+    """Classify approvals stored as either legacy session or RuntimeEvent rows."""
+
+    if event.event_type == EventType.APPROVAL_REQUESTED:
+        return "approval_request"
+    if event.event_type == EventType.APPROVAL_RESOLVED:
+        return "approval_response"
+    # canonical schema-v2:审批请求/应答是 interaction.* 事件。
+    if event.event_type == "interaction.requested":
+        return "approval_request"
+    if event.event_type in {"interaction.resolved", "approval.resolved"}:
+        return "approval_response"
+    return canonical_event_type(
+        event.event_type,
+        author=event.author,
+        role=str((event.content or {}).get("role") or ""),
+    )
+
+
+def _approval_interrupt_info_from_event(event: SessionEvent) -> dict[str, Any]:
+    """Read the approval payload without downgrading canonical RuntimeEvents.
+
+    RuntimeExecutor persists ``approval.requested`` as a RuntimeEvent envelope,
+    whereas legacy runners write an ``approval_request`` SessionEvent.  Resume
+    accepts both forms so the durable runtime record remains the source of truth.
+    """
+
+    metadata = event.metadata or {}
+    legacy_detail = metadata.get("interrupt_info")
+    if isinstance(legacy_detail, Mapping):
+        return dict(legacy_detail)
+
+    content = event.content or {}
+    # canonical schema-v2 envelope:content["runtime_event"]["request"]["detail"]
+    canonical_payload = content.get("runtime_event")
+    if isinstance(canonical_payload, Mapping):
+        request = canonical_payload.get("request")
+        if isinstance(request, Mapping):
+            raw_detail = request.get("detail")
+            detail = dict(raw_detail) if isinstance(raw_detail, Mapping) else {}
+            approval_id = request.get("call_id") or canonical_payload.get("interaction_id")
+            if approval_id:
+                detail.setdefault("approval_request_id", approval_id)
+                detail.setdefault("id", approval_id)
+            if request.get("call_id"):
+                detail.setdefault("run_id", request.get("call_id"))
+            return detail
+    payload = content.get("payload")
+    if not isinstance(payload, Mapping):
+        return {}
+    raw_detail = payload.get("detail")
+    detail = dict(raw_detail) if isinstance(raw_detail, Mapping) else {}
+    approval_id = payload.get("approval_id") or payload.get("call_id")
+    if approval_id:
+        detail.setdefault("approval_request_id", approval_id)
+        detail.setdefault("id", approval_id)
+    if payload.get("call_id"):
+        detail.setdefault("run_id", payload.get("call_id"))
+    return detail
+
+
 def _approval_resume_run_mode(
     events: Sequence[SessionEvent],
     resume_input: Mapping[str, Any],
@@ -167,11 +212,7 @@ def _approval_decision_from_resume(resume_input: Mapping[str, Any]) -> dict[str,
 def _consecutive_approval_denials_from_events(events: Sequence[SessionEvent]) -> int:
     denials = 0
     for event in reversed(events):
-        event_type = canonical_event_type(
-            event.event_type,
-            author=event.author,
-            role=str((event.content or {}).get("role") or ""),
-        )
+        event_type = _approval_lifecycle_event_type(event)
         if event_type != "approval_response":
             continue
         resume_input = (event.metadata or {}).get("resume_input")
@@ -210,9 +251,7 @@ def _normalize_approval_resume_input(
     if matched_event is None:
         return normalized
 
-    interrupt_info = (matched_event.metadata or {}).get("interrupt_info")
-    if not isinstance(interrupt_info, Mapping):
-        return normalized
+    interrupt_info = _approval_interrupt_info_from_event(matched_event)
     if not (interrupt_info.get("tool_name") or normalized.get("tool_name")):
         return normalized