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

ksadk/conversations/runtime_invocation.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import asyncio
 import json
+import time
 from typing import Any, Callable, Dict, Mapping, Optional, Sequence
 
 from ksadk.conversations.reasoning_markup import strip_reasoning_markup
@@ -32,10 +33,13 @@ from ksadk.conversations.runtime_metadata import _update_session_metadata_after_
 from ksadk.conversations.runtime_observability import (
     _conversation_span_scope,
     _normalize_usage_payload,
+    _set_context_plan_attributes,
     _set_conversation_input_attributes,
     _set_conversation_output_attributes,
     _set_conversation_span_attributes,
     _set_conversation_usage_attributes,
+    _set_prompt_cache_attributes,
+    _set_prompt_source_attributes,
     _span_feedback_metadata,
 )
 from ksadk.conversations.runtime_persistence import (
@@ -59,6 +63,42 @@ from ksadk.runtime_context import (
 from ksadk.sessions import resolve_session_service
 
 
+def _perf_monotonic() -> float:
+    return time.monotonic()
+
+
+def _record_baseline_turn(
+    *,
+    prepared: Any,
+    model: str | None,
+    usage: Mapping[str, Any] | None,
+    ptl: bool,
+    attempts: int,
+    turn_start_monotonic: float | None,
+) -> None:
+    """env-gated 旁路采集：未启用时 no-op，启用时记录一条 turn 基线。
+
+    只读 prepared.shadow_context_plan + usage + PTL/latency 信号，不进决策路径、不抛异常。
+    """
+    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,
+        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 invoke_conversation_once(
     *,
     runner: Any,
@@ -80,6 +120,9 @@ async def invoke_conversation_once(
     invocation_id: Optional[str] = None,
     session_service_provider: Callable[[], Any] | None = None,
     run_mode: str = RUN_MODE_FOREGROUND,
+    agent_system: str = "",
+    agent_task: str = "",
+    prompt_integration_mode: str = "",
 ) -> tuple[str, dict[str, Any]]:
     """非流式 turn 编排入口。
 
@@ -111,6 +154,11 @@ async def invoke_conversation_once(
             governance_state=governance,
             session_service_provider=provider,
             run_mode=entry_run_mode,
+            runner=runner,
+            runtime_type=_runner_type_name(runner),
+            agent_system=agent_system,
+            agent_task=agent_task,
+            prompt_integration_mode=prompt_integration_mode,
         )
         # prepared 之后的 run_status 写入复用 prepared 的 mode/trigger
         run_mode = prepared.run_mode
@@ -135,6 +183,7 @@ async def invoke_conversation_once(
         user_id=user_id,
         user_input=prepared.user_input,
     )
+    prepared.memory_recall_events = ambient_contexts.get("memory_recall_events", [])
     runtime_context = PlatformInvocationContext(
         agent_id=agent_id,
         user_id=user_id,
@@ -155,9 +204,7 @@ async def invoke_conversation_once(
         model_options=prepared.model_options,
         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 ""
-        ),
+        tool_approval_mode=str(prepared.request_metadata.get("tool_approval_mode") or ""),
     )
     runner_name = _runner_name(runner)
     async with _conversation_span_scope(runner_name) as span:
@@ -172,7 +219,11 @@ async def invoke_conversation_once(
             response_id=response_id,
         )
         _set_conversation_input_attributes(span, prepared.user_input or prepared.user_display_input)
+        _set_context_plan_attributes(span, prepared.shadow_context_plan)
         trace_metadata = _span_feedback_metadata(span)
+        _baseline_turn_start = _perf_monotonic()
+        _baseline_ptl = False
+        _baseline_attempts = 0
         await append_run_status_event(
             session_id=prepared.session_id,
             author=runner_name,
@@ -218,6 +269,8 @@ async def invoke_conversation_once(
                 raise
             except Exception as exc:
                 if attempt == 0 and _is_prompt_too_long_error(exc):
+                    _baseline_ptl = True
+                    _baseline_attempts = attempt + 1
                     try:
                         checkpoint = await _compact_conversation_history_with_governance(
                             governance,
@@ -230,6 +283,16 @@ async def invoke_conversation_once(
                             trigger="prompt_too_long",
                             keep_tail_groups=PTL_RETRY_KEEP_TAIL_GROUPS,
                             session_service_provider=provider,
+                            # PR D1：PTL 路径仍 force=True（trigger_band=emergency），
+                            # 透传 ownership 便于未来按门控调 PTL 策略；当前行为等价。
+                            prompt_integration_mode=getattr(
+                                prepared, "prompt_integration_mode", ""
+                            ),
+                            compaction_owner=str(
+                                (getattr(prepared, "shadow_context_plan", None) or {}).get(
+                                    "compaction_owner", ""
+                                )
+                            ),
                         )
                     except RuntimeCircuitOpen as circuit_exc:
                         await append_run_status_event(
@@ -293,6 +356,21 @@ async def invoke_conversation_once(
         ) or (result_usage if result_usage else {})
         _set_conversation_output_attributes(span, output_text)
         _set_conversation_usage_attributes(span, result_usage)
+        _set_prompt_cache_attributes(
+            span,
+            session_id=prepared.session_id,
+            plan=prepared.shadow_context_plan,
+            usage=result_usage,
+        )
+        _set_prompt_source_attributes(span, getattr(prepared, "compiled_prompt", None))
+        _record_baseline_turn(
+            prepared=prepared,
+            model=model,
+            usage=result_usage,
+            ptl=_baseline_ptl,
+            attempts=_baseline_attempts,
+            turn_start_monotonic=_baseline_turn_start,
+        )
         result_agentengine_metadata = _extract_agentengine_metadata(result)
         assistant_metadata: dict[str, Any] = {
             **trace_metadata,

ksadk/conversations/runtime_observability.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import json
 from contextlib import asynccontextmanager, nullcontext
 from typing import Any, Mapping, Sequence
 
@@ -94,13 +95,25 @@ def _responses_usage_payload(usage: Mapping[str, Any] | None) -> dict[str, Any]
     total_tokens = normalized.get("total_tokens", input_tokens + output_tokens)
     payload = {
         "input_tokens": input_tokens,
+        "input_tokens_details": {"cached_tokens": 0},
         "output_tokens": output_tokens,
+        "output_tokens_details": {"reasoning_tokens": 0},
         "total_tokens": total_tokens,
     }
-    if isinstance(normalized.get("input_token_details"), Mapping):
-        payload["input_token_details"] = dict(normalized["input_token_details"])
-    if isinstance(normalized.get("output_token_details"), Mapping):
-        payload["output_token_details"] = dict(normalized["output_token_details"])
+    input_details = normalized.get("input_token_details")
+    if isinstance(input_details, Mapping):
+        cached_tokens = input_details.get(
+            "cached_tokens",
+            input_details.get("cached", input_details.get("cache_read", 0)),
+        )
+        payload["input_tokens_details"]["cached_tokens"] = int(cached_tokens or 0)
+    output_details = normalized.get("output_token_details")
+    if isinstance(output_details, Mapping):
+        reasoning_tokens = output_details.get(
+            "reasoning_tokens",
+            output_details.get("reasoning", 0),
+        )
+        payload["output_tokens_details"]["reasoning_tokens"] = int(reasoning_tokens or 0)
     return payload
 
 
@@ -244,6 +257,62 @@ def _set_span_attribute(span: Any | None, key: str, value: Any) -> None:
         return
 
 
+def _set_context_plan_attributes(span: Any | None, plan: Any | None) -> None:
+    """把 shadow ContextPlan 的统计/ownership/精度挂到 conversation span。
+
+    ``plan`` 为 None 或空时直接 return，对现有 span 无影响。只记录 hash/统计/精度，
+    不落完整 Prompt/Memory/Tool 内容（方案 8.8 / 安全要求）。第一个 PR 只挂 plan_id/
+    policy_version/tokenizer/planned_input_tokens/integration_mode/accounting_accuracy/
+    tokens_by_kind(json)/stable_prefix_hash + ownership 摘要；projected/runtime_reported
+    等留后续 PR。
+    """
+    if span is None or not plan:
+        return
+    if not isinstance(plan, Mapping):
+        return
+    _set_span_attribute(span, "context.plan_id", plan.get("plan_id"))
+    _set_span_attribute(span, "context.policy_version", plan.get("policy_version"))
+    _set_span_attribute(span, "context.tokenizer", plan.get("tokenizer"))
+    _set_span_attribute(span, "context.deployment_mode", plan.get("deployment_mode"))
+    _set_span_attribute(span, "context.runtime_type", plan.get("runtime_type"))
+    _set_span_attribute(span, "context.planned_input_tokens", plan.get("planned_input_tokens"))
+    # 方案 §6.3：projected/runtime_reported 贯穿 Trace（缺口 6）。projected=Adapter 实际投影给
+    # Runner 的；runtime_reported=Provider/Runner 回报的实际。None 表示该口径不可得（诚实标注）。
+    _set_span_attribute(span, "context.projected_input_tokens", plan.get("projected_input_tokens"))
+    _set_span_attribute(
+        span, "context.runtime_reported_input_tokens", plan.get("runtime_reported_input_tokens")
+    )
+    _set_span_attribute(span, "context.integration_mode", plan.get("integration_mode"))
+    _set_span_attribute(span, "context.accounting_accuracy", plan.get("accounting_accuracy"))
+    _set_span_attribute(span, "context.prompt_owner", plan.get("prompt_owner"))
+    _set_span_attribute(span, "context.history_owner", plan.get("history_owner"))
+    _set_span_attribute(span, "context.compaction_owner", plan.get("compaction_owner"))
+    _set_span_attribute(span, "context.memory_owner", plan.get("memory_owner"))
+    _set_span_attribute(span, "context.skill_owner", plan.get("skill_owner"))
+    # 方案 §6.3 / 缺口 7：native compaction 不可见时的统一展示规范。compaction_owner=native 且
+    # actual 不可见时，标 compaction_visibility=opaque，不把 planned 伪装成 actual。
+    compaction_owner = str(plan.get("compaction_owner") or "")
+    accuracy = str(plan.get("accounting_accuracy") or "")
+    if compaction_owner == "native" and accuracy in ("opaque", "estimated"):
+        _set_span_attribute(span, "context.compaction_visibility", "opaque")
+        _set_span_attribute(
+            span,
+            "context.compaction_note",
+            "native runtime 内部 compaction 不可见，仅记录平台 projection",
+        )
+    tokens_by_kind = plan.get("tokens_by_kind")
+    if tokens_by_kind:
+        try:
+            _set_span_attribute(
+                span,
+                "context.tokens_by_kind",
+                json.dumps(dict(tokens_by_kind), ensure_ascii=False),
+            )
+        except (TypeError, ValueError):
+            pass
+    _set_span_attribute(span, "context.stable_prefix_hash", plan.get("stable_prefix_hash"))
+
+
 def _set_conversation_input_attributes(span: Any | None, input_text: str | None) -> None:
     text = " ".join(str(input_text or "").split())
     if not text:
@@ -353,3 +422,87 @@ def _set_conversation_span_attributes(
             span.set_attribute("ksadk.response_id", response_id)
     except Exception:
         return
+
+
+def _set_prompt_cache_attributes(
+    span: Any | None,
+    *,
+    session_id: str | None,
+    plan: Any | None,
+    usage: Mapping[str, Any] | None,
+) -> None:
+    """PR2：记录 shadow CompiledPrompt hash + Provider prompt cache 信号 + 失效诊断到 span。
+
+    ``plan`` 为 ``PreparedConversationTurn.shadow_context_plan``（plain dict）。``usage`` 为
+    Runtime 返回的 normalized usage。诊断用进程内 best-effort registry 记录上一稳定前缀，
+    pod 重启后清空，精度如实标注。只记录 hash/usage/break reason，不落完整 Prompt（安全要求）。
+    plan/usage 缺失时 no-op，对现有 span 无影响。
+    """
+    if span is None or not isinstance(plan, Mapping):
+        return
+    from ksadk.context_engine.cache_observability import (
+        diagnose_cache_break,
+        get_default_cache_break_registry,
+    )
+
+    stable_prefix_hash = str(
+        plan.get("prompt_stable_prefix_hash") or plan.get("stable_prefix_hash") or ""
+    )
+    accounting_accuracy = str(plan.get("accounting_accuracy") or "opaque")
+    _set_span_attribute(span, "prompt.content_hash", plan.get("prompt_content_hash"))
+    _set_span_attribute(span, "prompt.stable_prefix_hash", stable_prefix_hash or None)
+    section_hashes = plan.get("prompt_section_hashes")
+    if isinstance(section_hashes, Mapping) and section_hashes:
+        _set_span_attribute(span, "prompt.section_count", len(section_hashes))
+
+    registry = get_default_cache_break_registry()
+    previous_hash = registry.previous(session_id) if session_id else None
+    diagnosis = diagnose_cache_break(
+        stable_prefix_hash=stable_prefix_hash,
+        previous_stable_prefix_hash=previous_hash,
+        usage=usage,
+        accounting_accuracy=accounting_accuracy,  # type: ignore[arg-type]
+    )
+    _set_span_attribute(span, "prompt.cache.read_input_tokens", diagnosis.cache_read_tokens or None)
+    _set_span_attribute(
+        span, "prompt.cache.creation_input_tokens", diagnosis.cache_creation_tokens or None
+    )
+    _set_span_attribute(
+        span, "prompt.cache.expected_invalidation", diagnosis.expected_invalidation or None
+    )
+    _set_span_attribute(span, "prompt.cache.unexpected_break", diagnosis.unexpected_break or None)
+    _set_span_attribute(span, "prompt.cache.break_reason", diagnosis.break_reason or None)
+    _set_span_attribute(span, "prompt.cache.status", diagnosis.status)
+    # 记录本轮稳定前缀供下一轮诊断（best-effort，进程内）。
+    if session_id and stable_prefix_hash:
+        registry.record(session_id, stable_prefix_hash)
+
+
+def _set_prompt_source_attributes(span: Any | None, compiled_prompt: Any | None) -> None:
+    """PR A：记录真实 CompiledPrompt 的 source hash/version/section count 到 span。
+
+    ``compiled_prompt`` 为 ``PreparedConversationTurn.compiled_prompt``（plain dict，agent_system/
+    agent_task 非空时由 ResolvedPromptSources 编译）。None 时 no-op。只记 hash/version/count，
+    不记 Prompt 正文（安全要求）。
+    """
+    if span is None or not isinstance(compiled_prompt, Mapping):
+        return
+    section_hashes = compiled_prompt.get("prompt_section_hashes")
+    if isinstance(section_hashes, Mapping) and section_hashes:
+        _set_span_attribute(
+            span, "prompt.source.agent_system_hash", section_hashes.get("agent_identity")
+        )
+        _set_span_attribute(
+            span, "prompt.source.agent_task_hash", section_hashes.get("agent_policy")
+        )
+        _set_span_attribute(span, "prompt.source.section_count", len(section_hashes))
+    _set_span_attribute(
+        span,
+        "prompt.source.platform_policy_version",
+        compiled_prompt.get("prompt_platform_policy_version"),
+    )
+    _set_span_attribute(
+        span,
+        "prompt.source.resolved_sources_version",
+        compiled_prompt.get("prompt_resolved_sources_version"),
+    )

ksadk/conversations/runtime_payloads.py

@@ -55,6 +55,42 @@ class PreparedConversationTurn:
     request_history: list[dict[str, str]] = field(default_factory=list)
     request_responses_history: list[dict[str, Any]] = field(default_factory=list)
     responses_history: list[dict[str, Any]] = field(default_factory=list)
+    # shadow ContextPlan 的 plain dict 投影（P0 可观测基线）。
+    # 仅用启发式 tokenizer 按 kind 累加 tokens_by_kind + 标注 ownership/精度，
+    # 不进任何决策路径、不进 runner payload。None 表示尚未生成（resume 旁路也会填最小值）。
+    shadow_context_plan: dict[str, Any] | None = None
+    # PR A：真实 CompiledPrompt 的 plain dict 投影（agent_system/agent_task 非空时由
+    # ResolvedPromptSources 编译）。仅用于 hash/trace/future projection，不进 Runner payload。
+    # None=instructions-only 回退（canonical 路径无 agent_system/agent_task，或 resume 旁路）。
+    compiled_prompt: dict[str, Any] | None = None
+    # PR B：per-Build 接管标记。非空（"ksadk_hosted"）表示本 turn 由 ksadk 编译并接管
+    # Runner 的 instructions（仅 prompt_owner=ksadk + ksadk_hosted LangGraph 满足）。
+    # 默认空=framework 拥有，Runner 输入与旧逻辑一致。
+    prompt_integration_mode: str = ""
+    # PR D2：最新 checkpoint 的 WorkingState 审计 dict（仅 ksadk_hosted 路径填充）。
+    # 含 current_goal/active_files/pending_tools/pending_approvals/source_seq_range/content_hash。
+    # 用于门控重注入 Runner payload（非门控为 None，零注入）。
+    working_state: dict[str, Any] | None = None
+    # PR E：真实 ContextPlan 与组装输入（仅 ksadk_hosted + KSADK_CONTEXT_ENGINE_V2_ENABLED 时
+    # 由 hosted_pipeline 生成）。``context_plan`` 是 ``ContextPlan`` 的 plain dict 投影（含
+    # selected/decisions/budget），``assembled_input`` 是 AssembledInput 的 plain dict
+    memory_recall_events: list[dict[str, Any]] = field(default_factory=list)
+    # 平台 Memory Provider 的本轮召回结果。native runtime 由 Adapter 投影，
+    # framework/hosted 路径可继续通过 canonical payload 消费。
+    memory_context: dict[str, Any] | None = None
+    # （system + messages）。二者都进 trace 与 runner payload 接管；非门控为 None，零影响。
+    context_plan: dict[str, Any] | None = None
+    assembled_input: dict[str, Any] | None = None
+    # 可信 Principal，供平台 Memory 写入与召回使用。不能用 session_id 代替 user scope。
+    user_id: str = ""
+    agent_id: str = ""
+    # AgentVersion 级 Memory 写入灰度。None=旧环境策略；off/shadow=不写；enabled=写入。
+    memory_write_rollout: str | None = None
+    memory_enabled: bool | None = None
+    memory_recall_enabled: bool | None = None
+    memory_write_mode: str = "candidate"
+    flush_before_compaction: bool = True
+    provider_ref: str = "local-default"
 
 
 @dataclass
@@ -76,6 +112,12 @@ class CompactionPlan:
     compacted_until_seq_id: int | None = None
     pinned_group_indexes: list[int] = field(default_factory=list)
     pinned_state: dict[str, Any] = field(default_factory=dict)
+    # PR D1：双阈值（仅 ksadk_hosted 路径填充）。非门控路径为 None。
+    # trigger_band："" / "none" / "soft" / "hard" / "emergency"。empty=非门控走旧单阈值；
+    # "emergency"=PTL force。soft/hard 用于 proactive 整理 vs 强制压缩区分。
+    soft_limit_tokens: int | None = None
+    hard_limit_tokens: int | None = None
+    trigger_band: str = ""
 
 
 def build_responses_payload(