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

ksadk/conversations/projector.py

@@ -93,6 +93,12 @@ def project_conversation_item(
         schema = "conversation.item.tool-call/v1"
         payload = _tool_payload(event.initial)
         capability_ref = "tool.inspect"
+    elif isinstance(event, ItemSnapshotReplaced) and event.item_kind == "tool_call":
+        kind = "tool_call"
+        operation = "replace"
+        schema = "conversation.item.tool-call/v1"
+        payload = _tool_payload(event.snapshot)
+        capability_ref = "tool.inspect"
     elif isinstance(event, ItemCompleted) and event.item_kind == "tool_call":
         kind = "tool_call"
         operation = "completed"
@@ -100,6 +106,12 @@ def project_conversation_item(
         schema = "conversation.item.tool-call/v1"
         payload = _tool_payload(event.snapshot)
         capability_ref = "tool.inspect"
+    elif isinstance(event, (ItemUpdated, ItemSnapshotReplaced)) and event.item_kind == "tool_call":
+        kind = "tool_call"
+        operation = event.op if isinstance(event, ItemUpdated) else "replace"
+        schema = "conversation.item.tool-call/v1"
+        payload = _tool_payload(_item_snapshot(event))
+        capability_ref = "tool.inspect"
     elif (
         isinstance(event, (ItemStarted, ItemUpdated, ItemSnapshotReplaced, ItemCompleted))
         and event.item_kind == "tool_result"
@@ -253,6 +265,8 @@ def project_conversation_item(
             "status": "failed" if isinstance(event, RunFailed) else "canceled",
             "error": event.error.message if isinstance(event, RunFailed) else event.reason or "",
         }
+        if isinstance(event, RunFailed):
+            payload["errorCode"] = event.error.code
     elif isinstance(event, (ContinuationCreated, ContinuationResumed)):
         kind = "progress"
         schema = "conversation.item.checkpoint/v1"
@@ -310,6 +324,16 @@ def project_conversation_item(
                 "eventType": event.event_type,
                 "summary": "This content requires a newer renderer.",
             }
+    if isinstance(event, (RunCompleted, RunFailed, RunCanceled, RunInterrupted)):
+        payload.update(_run_outcome_payload(event.source.metadata))
+    if kind == "tool_call" and event.source.metadata.get("engine_kind") == "native":
+        # Native public results contain a sealed execution status, not arbitrary
+        # business output. An approval receipt is nonterminal even in old logs
+        # which incorrectly wrapped it in ItemCompleted. Never rewrite the log.
+        output = payload.get("output")
+        if isinstance(output, dict) and output.get("status") == "approval_required":
+            operation, lifecycle = "replace", "pending"
+            payload["executionStatus"] = "approval_required"
     return ConversationItem(
         item_id=item_id,
         source_event_ids=(event.event_id,),
@@ -330,6 +354,44 @@ def project_conversation_item(
     )
 
 
+def _run_outcome_payload(metadata: Mapping[str, Any]) -> dict[str, Any]:
+    """Project explicit acceptance facts; completion alone does not prove them.
+
+    Provider metadata is not a public payload. Only the terminal outcome contract
+    is admitted here; arbitrary diagnostics, reasoning and report contents stay
+    outside the conversation. Keep legacy terminal events without this contract.
+    """
+    outcome = metadata.get("outcome")
+    if not isinstance(outcome, str) or outcome not in {
+        "verified",
+        "unverified",
+        "partial",
+        "blocked",
+    }:
+        return {}
+    payload: dict[str, Any] = {"outcome": outcome}
+    for source, target in (
+        ("reason", "reason"),
+        ("contract_revision", "contractRevision"),
+        ("verification_report_ref", "verificationReportRef"),
+    ):
+        value = metadata.get(source)
+        if isinstance(value, str) and value:
+            payload[target] = value
+    items = metadata.get("verification_items")
+    if isinstance(items, list):
+        payload["verificationItems"] = [
+            {"acceptanceId": row["acceptance_id"], "status": row["status"]}
+            for row in items
+            if isinstance(row, dict)
+            and isinstance(row.get("acceptance_id"), str)
+            and row["acceptance_id"]
+            and isinstance(row.get("status"), str)
+            and row.get("status") in {"passed", "failed", "not_run", "blocked"}
+        ]
+    return payload
+
+
 def project_interaction_conversation_item(
     envelope: SessionEventEnvelope,
 ) -> ConversationItem | None:
@@ -604,6 +666,7 @@ def _native_ref(event: RuntimeEvent) -> dict[str, Any]:
             "protocol": source.protocol,
             "eventId": source.native_event_id,
             "cursor": source.native_cursor,
+            "timestamp": event.timestamp,
             "runId": source.native_run_id,
             "itemId": source.native_item_id,
         }.items()

ksadk/conversations/runtime_baseline.py

@@ -0,0 +1,37 @@
+"""Context-engine baseline recording kept outside the stream hot path."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Mapping
+from typing import Any
+
+
+def record_baseline_turn(
+    *,
+    prepared: Any,
+    model: str | None,
+    usage: Any,
+    ptl: bool,
+    attempts: int,
+    turn_start_monotonic: float | None,
+) -> None:
+    """Record one env-gated baseline turn without affecting decisions."""
+
+    from ksadk.context_engine.baseline import record_baseline_turn as record
+
+    latency_ms = None
+    if turn_start_monotonic is not None:
+        latency_ms = int((time.monotonic() - turn_start_monotonic) * 1000)
+    record(
+        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,
+    )

ksadk/conversations/runtime_compaction.py

@@ -231,7 +231,10 @@ async def preview_auto_compaction(
 
     provider = session_service_provider or resolve_session_service
     service = provider()
-    existing_session = await service.get_session(session_id)
+    # Attachment context lives in state; authorization/preview do not need a
+    # second complete transcript before the explicit get_events below.
+    read_metadata = getattr(service, "get_session_metadata", None) or service.get_session
+    existing_session = await read_metadata(session_id)
     if not existing_session:
         return CompactionPlan(
             should_compact=False,
@@ -378,7 +381,9 @@ async def compact_conversation_history(
     provider = session_service_provider or resolve_session_service
     service = provider()
     events = await service.get_events(session_id)
-    session = await service.get_session(session_id)
+    header_reader = getattr(service, "get_session_header", None) or getattr(
+        service, "get_session_metadata", None) or service.get_session
+    session = await header_reader(session_id)
     memory_user_id = str(getattr(session, "user_id", "") or "")
     plan = _plan_compaction(
         events,

ksadk/conversations/runtime_input.py

@@ -750,10 +750,22 @@ async def _auto_save_ltm_turn(
 ) -> None:
     if prepared.resume_input is not None:
         return
-    memory_rollout = str(prepared.memory_write_rollout or "").strip().lower()
-    if memory_rollout in {"off", "shadow"}:
-        return
-    if not memory_rollout and not _ltm_auto_save_enabled():
+    from ksadk.memory.resolved_policy import resolve_memory_policy
+
+    memory_rollout = prepared.memory_write_rollout
+    if not str(memory_rollout or "").strip():
+        memory_rollout = "enabled" if _ltm_auto_save_enabled() else "off"
+    # Old callers have no MemorySpec and retain the SDK auto-save fallback.
+    # Explicit Build switches always govern before opening a memory service.
+    policy = resolve_memory_policy(
+        memory_enabled=True if prepared.memory_enabled is None else prepared.memory_enabled,
+        recall_enabled=prepared.memory_recall_enabled,
+        write_rollout=memory_rollout,
+        write_mode=prepared.memory_write_mode,
+        flush_before_compaction=prepared.flush_before_compaction,
+        provider_ref=prepared.provider_ref,
+    )
+    if not policy.should_flush:
         return
 
     metadata: dict[str, Any] = {

ksadk/conversations/runtime_invocation.py

@@ -40,6 +40,7 @@ from ksadk.conversations.runtime_observability import (
     _set_conversation_usage_attributes,
     _set_prompt_cache_attributes,
     _set_prompt_source_attributes,
+    _set_skill_eval_result_attributes,
     _span_feedback_metadata,
 )
 from ksadk.conversations.runtime_persistence import (
@@ -55,7 +56,10 @@ from ksadk.conversations.runtime_resume import (
     _merge_agentengine_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 (
+    TRUSTED_IDENTITY_METADATA_KEY,
+    PlatformIdentityContext,
     PlatformInvocationContext,
     platform_invocation_scope,
     tool_execution_scope,
@@ -180,9 +184,13 @@ async def invoke_conversation_once(
             )
         raise
     _inject_runner_deferred_tools_for_request(runner, prepared)
+    effective_user_id = prepared.user_id or user_id
+    invocation_identity = PlatformIdentityContext.from_payload(
+        dict(request_metadata or {}).get(TRUSTED_IDENTITY_METADATA_KEY)
+    )
     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", [])
@@ -191,7 +199,7 @@ async def invoke_conversation_once(
     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),
@@ -210,13 +218,14 @@ async def invoke_conversation_once(
         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,
     )
     runner_name = _runner_name(runner)
     async with _conversation_span_scope(runner_name) as span:
         _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,
@@ -354,6 +363,9 @@ async def invoke_conversation_once(
         if last_invoke_error is not None:
             raise last_invoke_error
         result = result or {}
+        result_fields = skill_eval_response_fields(result)
+        if result_fields:
+            _set_skill_eval_result_attributes(span, result_fields["skill_eval_result"])
         output_text = strip_reasoning_markup(str(result.get("output", "")))
         result_usage = _normalize_usage_payload(result.get("usage"))
         result_last_usage = _normalize_usage_payload(
@@ -434,7 +446,7 @@ async def invoke_conversation_once(
         )
         await _auto_save_ltm_turn(
             agent_id=agent_id,
-            user_id=user_id,
+            user_id=effective_user_id,
             prepared=prepared,
             output_text=output_text,
             runner_type=runtime_context.runner_type,
@@ -450,6 +462,7 @@ async def invoke_conversation_once(
             run_trigger=run_trigger,
         )
         result_payload: dict[str, Any] = {
+            **result_fields,
             "output_text": output_text,
             "model": model,
             "metadata": {

ksadk/conversations/runtime_observability.py

@@ -45,6 +45,8 @@ def _normalize_usage_payload(usage: Mapping[str, Any] | None) -> dict[str, Any]:
         "total_tokens",
         "prompt_tokens",
         "completion_tokens",
+        "cached_tokens",
+        "reasoning_tokens",
     ):
         value = usage.get(key)
         if value is None:
@@ -57,6 +59,23 @@ def _normalize_usage_payload(usage: Mapping[str, Any] | None) -> dict[str, Any]:
         value = usage.get(key)
         if isinstance(value, Mapping):
             normalized[key] = dict(value)
+    for source_key, target_key in (
+        ("input_tokens_details", "input_token_details"),
+        ("output_tokens_details", "output_token_details"),
+    ):
+        value = usage.get(source_key)
+        if isinstance(value, Mapping) and target_key not in normalized:
+            normalized[target_key] = dict(value)
+    cached_tokens = normalized.get("cached_tokens")
+    if cached_tokens is not None:
+        input_details = normalized.setdefault("input_token_details", {})
+        if not any(key in input_details for key in ("cached_tokens", "cached", "cache_read")):
+            input_details["cached"] = cached_tokens
+    reasoning_tokens = normalized.get("reasoning_tokens")
+    if reasoning_tokens is not None:
+        output_details = normalized.setdefault("output_token_details", {})
+        if not any(key in output_details for key in ("reasoning_tokens", "reasoning")):
+            output_details["reasoning"] = reasoning_tokens
     prompt_details = usage.get("prompt_tokens_details")
     if isinstance(prompt_details, Mapping):
         normalized["prompt_tokens_details"] = dict(prompt_details)
@@ -339,10 +358,21 @@ def _set_conversation_output_attributes(span: Any | None, output_text: str | Non
         _set_span_attribute(span, key, text)
 
 
+def _set_skill_eval_result_attributes(span: Any | None, result: Mapping[str, Any]) -> None:
+    """Attach structured evidence without changing trace/observation output text."""
+    payload = json.dumps({"skill_eval_result": dict(result)}, ensure_ascii=False)
+    _set_span_attribute(span, "metadata", payload)
+    _set_span_attribute(
+        span, "langfuse.trace.metadata.skill_eval_result",
+        json.dumps(dict(result), ensure_ascii=False),
+    )
+
+
 def _set_conversation_usage_attributes(
     span: Any | None,
     usage: Mapping[str, Any] | None,
 ) -> None:
+    """Write run-level usage as KsADK diagnostics, never as model generation usage."""
     normalized = _normalize_usage_payload(usage)
     if not normalized:
         return
@@ -372,19 +402,14 @@ def _set_conversation_usage_attributes(
         )
 
     attributes = {
-        "gen_ai.usage.input_tokens": input_tokens,
-        "gen_ai.usage.output_tokens": output_tokens,
-        "gen_ai.usage.total_tokens": total_tokens,
-        "llm.usage.prompt_tokens": input_tokens,
-        "llm.usage.completion_tokens": output_tokens,
-        "llm.usage.total_tokens": total_tokens,
+        "ksadk.runtime.usage.input_tokens": input_tokens,
+        "ksadk.runtime.usage.output_tokens": output_tokens,
+        "ksadk.runtime.usage.total_tokens": total_tokens,
     }
     if cache_read_tokens:
-        attributes["gen_ai.usage.cache_read.input_tokens"] = cache_read_tokens
-        attributes["llm.usage.cache_read.input_tokens"] = cache_read_tokens
+        attributes["ksadk.runtime.usage.cache_read.input_tokens"] = cache_read_tokens
     if reasoning_tokens:
-        attributes["gen_ai.usage.reasoning.output_tokens"] = reasoning_tokens
-        attributes["llm.usage.reasoning_tokens"] = reasoning_tokens
+        attributes["ksadk.runtime.usage.reasoning.output_tokens"] = reasoning_tokens
 
     for key, value in attributes.items():
         if value:
@@ -405,6 +430,10 @@ def _set_conversation_span_attributes(
     if span is None:
         return
     try:
+        # A conversation span wraps the whole run. Real token-bearing model
+        # calls are separate child generations; keep this span out of the
+        # generation namespace so trace aggregation does not double-count.
+        span.set_attribute("openinference.span.kind", "AGENT")
         span.set_attribute("ksadk.agent_id", agent_id)
         span.set_attribute("ksadk.user_id", user_id)
         span.set_attribute("ksadk.session_id", session_id)

ksadk/conversations/runtime_payloads.py

@@ -15,6 +15,8 @@ from ksadk.conversations.runtime_observability import (
     _responses_usage_payload,
     _usage_from_metadata,
 )
+from ksadk.runtime.skill_eval_result import skill_eval_response_fields
+from ksadk.runtime.timing import normalize_timing
 from ksadk.sessions import SessionEvent
 
 
@@ -131,6 +133,8 @@ def build_responses_payload(
     status: str = "completed",
     metadata: Mapping[str, Any] | None = None,
     usage: Mapping[str, Any] | None = None,
+    timing: Mapping[str, Any] | None = None,
+    skill_eval_result: Mapping[str, Any] | None = None,
     incomplete_details: Mapping[str, Any] | None = None,
     error: Mapping[str, Any] | None = None,
     output_items: Sequence[Mapping[str, Any]] | None = None,
@@ -174,7 +178,11 @@ def build_responses_payload(
         "tools": [],
         "output": output,
         "output_text": output_text,
+        **skill_eval_response_fields({"skill_eval_result": skill_eval_result}),
         "usage": usage_payload,
+        **(
+            {"timing": normalized_timing} if (normalized_timing := normalize_timing(timing)) else {}
+        ),
         "session_id": session_id,
     }
 
@@ -209,6 +217,8 @@ def extract_responses_resume_input(input_payload: Any) -> dict[str, Any] | None:
             approval_resume: dict[str, Any] = {"type": "mcp_approval_response"}
             if item.get("id"):
                 approval_resume["id"] = str(item.get("id"))
+            if item.get("checkpoint_id"):
+                approval_resume["checkpoint_id"] = str(item.get("checkpoint_id"))
             approval_request_id = item.get("approval_request_id")
             if approval_request_id:
                 approval_resume["approval_request_id"] = str(approval_request_id)
@@ -235,6 +245,8 @@ def extract_responses_resume_input(input_payload: Any) -> dict[str, Any] | None:
 
         if item_type in {"ksadk_resume", "ksadk.approval_response"}:
             ksadk_resume: dict[str, Any] = {"type": "ksadk_resume"}
+            if item.get("checkpoint_id"):
+                ksadk_resume["checkpoint_id"] = str(item.get("checkpoint_id"))
             interrupt_id = (
                 item.get("interrupt_id") or item.get("approval_request_id") or item.get("id")
             )