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

ksadk/studio/operations.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import asyncio
 import json
+import logging
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Awaitable, Callable, cast
@@ -20,6 +21,8 @@ from ksadk.studio.contracts import (
 from ksadk.studio.errors import StudioError, not_found
 from ksadk.studio.workspace import Workspace
 
+logger = logging.getLogger(__name__)
+
 
 class OperationManager:
     def __init__(self, workspace: Workspace) -> None:
@@ -33,7 +36,8 @@ class OperationManager:
         kind: OperationKind,
         resource_id: str,
         idempotency_key: str,
-        runner: Callable[[], Awaitable[object]],
+        metadata: dict | None = None,
+        runner: Callable[[str], Awaitable[object]],
     ) -> Operation:
         existing = self._find_by_idempotency_key(idempotency_key)
         if existing is not None:
@@ -42,6 +46,7 @@ class OperationManager:
             id=f"op_{uuid4().hex}",
             kind=kind,
             resource_id=resource_id,
+            metadata=metadata or {},
         )
         self._write(operation, [], idempotency_key)
         self.append(operation.id, "operation.queued", {"kind": kind})
@@ -57,14 +62,14 @@ class OperationManager:
     async def _run(
         self,
         operation_id: str,
-        runner: Callable[[], Awaitable[object]],
+        runner: Callable[[str], Awaitable[object]],
     ) -> None:
         operation = self.get(operation_id)
         operation.status = OperationStatus.RUNNING
         self._save_record(operation)
         self.append(operation_id, "operation.started", {})
         try:
-            result = await runner()
+            result = await runner(operation_id)
             result_id = getattr(result, "id", None)
             if result_id:
                 operation.resource_id = str(result_id)
@@ -91,12 +96,22 @@ class OperationManager:
             operation.completed_at = datetime.now(timezone.utc)
             self._save_record(operation)
             self.append(operation_id, "operation.failed", operation.error)
-        except Exception:
+        except Exception as exc:
+            # Keep the browser response generic so an exception cannot leak a
+            # credential, but retain the traceback in the local Studio log for
+            # an operator to diagnose a failed deployment.
+            logger.exception("Studio operation failed: operation_id=%s", operation_id)
             operation.status = OperationStatus.FAILED
             operation.error = {
                 "code": "INTERNAL_ERROR",
                 "message": "本地操作执行失败",
+                "exceptionType": type(exc).__name__,
             }
+            # TypeError carries only Python call-shape information and is safe
+            # to surface to the local operator.  Do not expose arbitrary
+            # exception text: it may include provider request data.
+            if isinstance(exc, TypeError):
+                operation.error["exceptionMessage"] = str(exc)
             operation.completed_at = datetime.now(timezone.utc)
             self._save_record(operation)
             self.append(operation_id, "operation.failed", operation.error)
@@ -105,6 +120,18 @@ class OperationManager:
         operation, _, _ = self._read(operation_id)
         return operation
 
+    def list(self, *, kind: OperationKind | None = None) -> list[Operation]:
+        directory = self.workspace.resolve(".agentkit/operations")
+        operations: list[Operation] = []
+        for path in directory.glob("op_*.json"):
+            try:
+                operation = self.get(path.stem)
+            except StudioError:
+                continue
+            if kind is None or operation.kind == kind:
+                operations.append(operation)
+        return sorted(operations, key=lambda item: item.created_at, reverse=True)
+
     def events(self, operation_id: str, *, after: int = 0) -> list[OperationEvent]:
         _, events, _ = self._read(operation_id)
         return [event for event in events if event.id > after]
@@ -133,7 +160,12 @@ class OperationManager:
         task = self._tasks.get(operation_id)
         if task is not None:
             task.cancel()
-        return operation
+        if operation.status == OperationStatus.QUEUED:
+            operation.status = OperationStatus.CANCELLED
+            operation.completed_at = datetime.now(timezone.utc)
+            self._save_record(operation)
+            self.append(operation_id, "operation.cancelled", {})
+        return self.get(operation_id)
 
     async def wait(self, operation_id: str, *, timeout: float = 30) -> Operation:
         deadline = asyncio.get_running_loop().time() + timeout

ksadk/studio/otel_trace.py

@@ -149,6 +149,270 @@ def _enum_string(value: Any) -> str:
     return str(getattr(value, "value", value))
 
 
+def _token_value(attributes: dict[str, Any], *keys: str) -> int | None:
+    """Read one non-negative token counter from known OTLP attribute names."""
+
+    for key in keys:
+        value = attributes.get(key)
+        if value is None or isinstance(value, bool):
+            continue
+        try:
+            normalized = int(value)
+        except (TypeError, ValueError):
+            continue
+        if normalized >= 0:
+            return normalized
+    return None
+
+
+def _usage_from_attributes(attributes: dict[str, Any]) -> dict[str, Any]:
+    """Normalize AgentKit and standard GenAI usage without trusting a side flag."""
+
+    input_tokens = _token_value(
+        attributes,
+        "gen_ai.usage.input_tokens",
+        "agentkit.usage.input_tokens",
+    )
+    output_tokens = _token_value(
+        attributes,
+        "gen_ai.usage.output_tokens",
+        "agentkit.usage.output_tokens",
+    )
+    total_tokens = _token_value(
+        attributes,
+        "agentkit.usage.total_tokens",
+        "gen_ai.usage.total_tokens",
+    )
+    cached_input_tokens = _token_value(
+        attributes,
+        "gen_ai.usage.cache_read.input_tokens",
+        "gen_ai.usage.cached_input_tokens",
+        "llm.usage.cache_read.input_tokens",
+        "agentkit.usage.cached_input_tokens",
+    )
+    reasoning_output_tokens = _token_value(
+        attributes,
+        "gen_ai.usage.reasoning.output_tokens",
+        "gen_ai.usage.reasoning_tokens",
+        "gen_ai.usage.reasoning_output_tokens",
+        "llm.usage.reasoning_tokens",
+        "agentkit.usage.reasoning_output_tokens",
+    )
+    if total_tokens is None and input_tokens is not None and output_tokens is not None:
+        total_tokens = input_tokens + output_tokens
+    reported = any(
+        value is not None
+        for value in (
+            input_tokens,
+            output_tokens,
+            total_tokens,
+            cached_input_tokens,
+            reasoning_output_tokens,
+        )
+    )
+    source = attributes.get("agentkit.usage.source")
+    if not source and reported:
+        source = "gen_ai.usage"
+    return {
+        "inputTokens": input_tokens,
+        "outputTokens": output_tokens,
+        "totalTokens": total_tokens,
+        "cachedInputTokens": cached_input_tokens,
+        "reasoningOutputTokens": reasoning_output_tokens,
+        "usageCompleteness": {
+            "inputTokens": input_tokens is not None,
+            "outputTokens": output_tokens is not None,
+            "totalTokens": total_tokens is not None,
+            "cachedInputTokens": cached_input_tokens is not None,
+            "reasoningOutputTokens": reasoning_output_tokens is not None,
+        },
+        "usageReported": reported,
+        "usageSource": source,
+    }
+
+
+def _aggregate_span_usage(spans: Iterable[dict[str, Any]]) -> dict[str, Any]:
+    """Aggregate billing spans and collapse only exact compatibility wrappers."""
+
+    span_list = list(spans)
+    usage_by_id: dict[str, dict[str, Any]] = {}
+    children_by_parent: dict[str, list[str]] = {}
+    parent_by_id: dict[str, str] = {}
+    anonymous_usages: list[dict[str, Any]] = []
+    for span in span_list:
+        span_id = str(span.get("spanId") or "")
+        parent_id = str(span.get("parentSpanId") or "")
+        usage = _usage_from_attributes(_decoded_attributes(span.get("attributes", [])))
+        if span_id:
+            usage_by_id[span_id] = usage
+            parent_by_id[span_id] = parent_id
+            if parent_id:
+                children_by_parent.setdefault(parent_id, []).append(span_id)
+        elif usage["usageReported"]:
+            anonymous_usages.append(usage)
+
+    usage_fields = (
+        "inputTokens",
+        "outputTokens",
+        "totalTokens",
+        "cachedInputTokens",
+        "reasoningOutputTokens",
+    )
+
+    def empty_aggregate() -> dict[str, Any]:
+        return {
+            **{key: None for key in usage_fields},
+            "usageCompleteness": {key: False for key in usage_fields},
+            "billingSpanCount": 0,
+            "usageReported": False,
+            "usageSource": None,
+        }
+
+    def billed_usage(usage: dict[str, Any]) -> dict[str, Any]:
+        return {
+            **{key: usage[key] for key in usage_fields},
+            "usageCompleteness": dict(usage["usageCompleteness"]),
+            "billingSpanCount": 1,
+            "usageReported": True,
+            "usageSource": usage["usageSource"],
+        }
+
+    def combine(parts: Iterable[dict[str, Any]]) -> dict[str, Any]:
+        billed_parts = [part for part in parts if part["billingSpanCount"] > 0]
+        if not billed_parts:
+            return empty_aggregate()
+        aggregate = empty_aggregate()
+        aggregate["billingSpanCount"] = sum(part["billingSpanCount"] for part in billed_parts)
+        aggregate["usageReported"] = True
+        aggregate["usageSource"] = next(
+            (part["usageSource"] for part in billed_parts if part["usageSource"]),
+            "gen_ai.usage",
+        )
+        for key in usage_fields:
+            values = [part[key] for part in billed_parts if part[key] is not None]
+            aggregate[key] = sum(values) if values else None
+            aggregate["usageCompleteness"][key] = all(
+                part["usageCompleteness"][key] for part in billed_parts
+            )
+        return aggregate
+
+    def is_compatibility_wrapper(
+        own_usage: dict[str, Any], descendant_usage: dict[str, Any]
+    ) -> bool:
+        if descendant_usage["billingSpanCount"] == 0:
+            return False
+        if own_usage["inputTokens"] is None or own_usage["outputTokens"] is None:
+            return False
+        return all(
+            descendant_usage["usageCompleteness"][key] and descendant_usage[key] == own_usage[key]
+            for key in ("inputTokens", "outputTokens")
+        ) and all(
+            own_usage[key] is None
+            or (
+                descendant_usage["usageCompleteness"][key]
+                and descendant_usage[key] == own_usage[key]
+            )
+            for key in ("inputTokens", "outputTokens", "totalTokens")
+        )
+
+    memo: dict[str, dict[str, Any]] = {}
+
+    def aggregate_subtree(span_id: str, visiting: set[str] | None = None) -> dict[str, Any]:
+        if span_id in memo:
+            return memo[span_id]
+        active = set() if visiting is None else visiting
+        if span_id in active:
+            return empty_aggregate()
+        active.add(span_id)
+        descendants = combine(
+            aggregate_subtree(child_id, active) for child_id in children_by_parent.get(span_id, [])
+        )
+        active.remove(span_id)
+        own_usage = usage_by_id[span_id]
+        if not own_usage["usageReported"]:
+            result = descendants
+        elif is_compatibility_wrapper(own_usage, descendants):
+            result = descendants
+            for key in usage_fields:
+                if own_usage[key] is not None:
+                    result[key] = own_usage[key]
+                    result["usageCompleteness"][key] = True
+        else:
+            result = combine((billed_usage(own_usage), descendants))
+        memo[span_id] = result
+        return result
+
+    roots = [
+        span_id
+        for span_id in usage_by_id
+        if not parent_by_id[span_id] or parent_by_id[span_id] not in usage_by_id
+    ]
+    aggregate = combine(aggregate_subtree(span_id) for span_id in roots)
+    for span_id in usage_by_id:
+        if span_id not in memo:
+            aggregate = combine((aggregate, aggregate_subtree(span_id)))
+    aggregate = combine((aggregate, *(billed_usage(usage) for usage in anonymous_usages)))
+    if aggregate["billingSpanCount"] == 0:
+        return _usage_from_attributes({})
+    if not aggregate["usageCompleteness"]["totalTokens"]:
+        aggregate["totalTokens"] = None
+    aggregate.pop("billingSpanCount", None)
+    return aggregate
+
+
+def _merge_usage(primary: dict[str, Any], fallback: dict[str, Any]) -> dict[str, Any]:
+    """Keep explicit root counters and fill only absent fields from leaf usage."""
+
+    merged: dict[str, Any] = {
+        key: primary[key] if primary[key] is not None else fallback[key]
+        for key in (
+            "inputTokens",
+            "outputTokens",
+            "cachedInputTokens",
+            "reasoningOutputTokens",
+        )
+    }
+    completeness = {
+        key: (
+            primary["usageCompleteness"][key]
+            if primary[key] is not None
+            else fallback["usageCompleteness"][key]
+        )
+        for key in (
+            "inputTokens",
+            "outputTokens",
+            "cachedInputTokens",
+            "reasoningOutputTokens",
+        )
+    }
+    if primary["totalTokens"] is not None:
+        merged["totalTokens"] = primary["totalTokens"]
+        completeness["totalTokens"] = primary["usageCompleteness"]["totalTokens"]
+    elif (
+        merged["inputTokens"] is not None
+        and merged["outputTokens"] is not None
+        and completeness["inputTokens"]
+        and completeness["outputTokens"]
+    ):
+        merged["totalTokens"] = merged["inputTokens"] + merged["outputTokens"]
+        completeness["totalTokens"] = True
+    elif primary["inputTokens"] is None and primary["outputTokens"] is None:
+        merged["totalTokens"] = (
+            fallback["totalTokens"] if fallback["usageCompleteness"]["totalTokens"] else None
+        )
+        completeness["totalTokens"] = fallback["usageCompleteness"]["totalTokens"]
+    else:
+        merged["totalTokens"] = None
+        completeness["totalTokens"] = False
+    reported = primary["usageReported"] or fallback["usageReported"]
+    return {
+        **merged,
+        "usageCompleteness": completeness,
+        "usageReported": reported,
+        "usageSource": primary["usageSource"] or fallback["usageSource"],
+    }
+
+
 class OtlpTraceStore:
     """Persist one canonical OTLP JSON document per local Trace."""
 
@@ -188,37 +452,15 @@ class OtlpTraceStore:
         root_attributes = _decoded_attributes(root.get("attributes", []))
         canonical = root["traceId"]
         duration = root_attributes.get("agentkit.duration.ms")
-        usage_reported = bool(root_attributes.get("agentkit.usage.reported", False))
+        root_usage = _usage_from_attributes(root_attributes)
+        leaf_usage = _aggregate_span_usage(
+            span for span in spans if span.get("spanId") != root.get("spanId")
+        )
+        usage = _merge_usage(root_usage, leaf_usage)
         metrics = {
             "durationMs": int(duration) if duration is not None else None,
             "durationSource": root_attributes.get("agentkit.duration.source"),
-            "inputTokens": (
-                int(root_attributes["gen_ai.usage.input_tokens"])
-                if usage_reported and "gen_ai.usage.input_tokens" in root_attributes
-                else None
-            ),
-            "outputTokens": (
-                int(root_attributes["gen_ai.usage.output_tokens"])
-                if usage_reported and "gen_ai.usage.output_tokens" in root_attributes
-                else None
-            ),
-            "totalTokens": (
-                int(root_attributes["agentkit.usage.total_tokens"])
-                if usage_reported and "agentkit.usage.total_tokens" in root_attributes
-                else None
-            ),
-            "cachedInputTokens": (
-                int(root_attributes.get("gen_ai.usage.cached_input_tokens", 0))
-                if usage_reported
-                else None
-            ),
-            "reasoningOutputTokens": (
-                int(root_attributes.get("gen_ai.usage.reasoning_tokens", 0))
-                if usage_reported
-                else None
-            ),
-            "usageReported": usage_reported,
-            "usageSource": root_attributes.get("agentkit.usage.source"),
+            **usage,
         }
         first_resource = (raw.get("resourceSpans") or [{}])[0]
         first_scope = (first_resource.get("scopeSpans") or [{}])[0]
@@ -343,6 +585,7 @@ class OtlpTraceStore:
                     "outputTokens": metrics["outputTokens"],
                     "totalTokens": metrics["totalTokens"],
                     "usageReported": metrics["usageReported"],
+                    "usageCompleteness": metrics["usageCompleteness"],
                     "spanCount": len(view["spans"]),
                     "target": view["target"],
                 }
@@ -451,11 +694,13 @@ class OtlpTraceStore:
         root_end = (
             root_start + record.duration_ms * 1_000_000
             if record.duration_ms is not None
-            else _unix_nano(record.completed_at)
-            if record.completed_at is not None
-            else _unix_nano(events[-1].created_at)
-            if events
-            else root_start
+            else (
+                _unix_nano(record.completed_at)
+                if record.completed_at is not None
+                else _unix_nano(events[-1].created_at)
+                if events
+                else root_start
+            )
         )
         run_status = _enum_string(record.status)
         root_attributes: dict[str, Any] = {
@@ -546,15 +791,76 @@ class OtlpTraceStore:
             "tool.requested",
             "tool.completed",
         }
-        return [
-            {
-                "timeUnixNano": str(_unix_nano(event.created_at)),
-                "name": event.type,
-                "attributes": _attributes(_safe_event_attributes(event.data)),
-            }
-            for event in events
-            if event.type not in excluded
-        ]
+        content_families = {
+            "thinking.delta": "thinking",
+            "thinking.completed": "thinking",
+            "message.delta": "message",
+            "message.completed": "message",
+        }
+        projected: list[dict[str, Any]] = []
+        content_groups: dict[tuple[str, str, str, str], list[RunEvent]] = {}
+        current_turn = ""
+        current_step = ""
+
+        for event in events:
+            runtime_event = event.data.get("runtimeEvent")
+            correlation = runtime_event if isinstance(runtime_event, dict) else {}
+            turn_id = str(correlation.get("turn_id") or "")
+            step_id = str(correlation.get("step_id") or "")
+            if turn_id:
+                current_turn = turn_id
+            if step_id and event.type in {"step.started", "model.call.begin"}:
+                current_step = step_id
+
+            family = content_families.get(event.type)
+            if family:
+                key = (
+                    event.run_id,
+                    turn_id or current_turn,
+                    step_id or current_step,
+                    family,
+                )
+                content_groups.setdefault(key, []).append(event)
+                continue
+            if event.type in excluded:
+                continue
+            projected.append(
+                {
+                    "timeUnixNano": str(_unix_nano(event.created_at)),
+                    "name": event.type,
+                    "attributes": _attributes(_safe_event_attributes(event.data)),
+                }
+            )
+
+        for grouped in content_groups.values():
+            completed = next(
+                (event for event in reversed(grouped) if event.type.endswith(".completed")),
+                None,
+            )
+            source = completed or grouped[-1]
+            completed_text = source.data.get("text") if completed is not None else None
+            text = (
+                completed_text
+                if isinstance(completed_text, str) and completed_text
+                else "".join(
+                    str(event.data.get("text") or "")
+                    for event in grouped
+                    if event.type.endswith(".delta")
+                )
+            )
+            data = dict(source.data)
+            data["text"] = text
+            data["delta_count"] = sum(event.type.endswith(".delta") for event in grouped)
+            projected.append(
+                {
+                    "timeUnixNano": str(_unix_nano(source.created_at)),
+                    "name": source.type,
+                    "attributes": _attributes(_safe_event_attributes(data)),
+                }
+            )
+
+        projected.sort(key=lambda event: int(event["timeUnixNano"]))
+        return projected
 
     def _model_spans(
         self, trace_id: str, root_id: str, events: list[RunEvent], root_end: int

ksadk/studio/pcm_memory.py

@@ -0,0 +1,85 @@
+"""Studio-side projection helpers for platform-owned PCM memory."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ksadk.memory.coordinator import (
+    MemoryCoordinator,
+    agent_user_scope_id,
+    build_search_request,
+    recall_to_context_item,
+)
+from ksadk.memory.events import recall_completed, recall_empty, recall_failed
+from ksadk.memory.provider_adapter import adapt_as_memory_provider
+from ksadk.memory.provider_resolver import resolve_memory_provider
+
+
+def recall_platform_memory(
+    *,
+    run_id: str,
+    session_id: str,
+    agent_id: str,
+    user_id: str,
+    user_input: str,
+    request_config: dict[str, Any],
+) -> tuple[dict[str, Any] | None, list[dict[str, Any]]]:
+    """Recall agent-scoped memory and return its auditable lifecycle event."""
+
+    if not bool(request_config.get("memory_enabled")) or not bool(
+        request_config.get("memory_recall_enabled", True)
+    ):
+        return None, []
+
+    provider_ref = str(request_config.get("provider_ref") or "local-default")
+    rollout = str(request_config.get("memory_write_rollout") or "enabled")
+    try:
+        provider = adapt_as_memory_provider(resolve_memory_provider(provider_ref))
+        result = MemoryCoordinator(provider).recall(
+            build_search_request(
+                query=user_input,
+                user_id=agent_user_scope_id(agent_id=agent_id, user_id=user_id),
+                top_k=int(request_config.get("memory_recall_top_k") or 8),
+                max_tokens=int(request_config.get("memory_recall_max_tokens") or 1600),
+                min_score=float(request_config.get("memory_recall_min_score") or 0.45),
+            )
+        )
+        context = recall_to_context_item(result)
+        if context is not None:
+            event = recall_completed(
+                run_id=run_id,
+                session_id=session_id,
+                provider=provider_ref,
+                rollout=rollout,
+                count=len(result.records),
+            )
+        elif result.status == "ok":
+            event = recall_empty(
+                run_id=run_id,
+                session_id=session_id,
+                provider=provider_ref,
+                rollout=rollout,
+            )
+        else:
+            event = recall_failed(
+                run_id=run_id,
+                session_id=session_id,
+                provider=provider_ref,
+                rollout=rollout,
+                error_code=str(result.error_code or result.status),
+                error_message="平台长期记忆召回失败",
+                retryable=result.status in {"timeout", "failed"},
+            )
+        return context, [event.to_dict()]
+    except Exception as exc:  # noqa: BLE001 - recall failure must not break a run
+        return None, [
+            recall_failed(
+                run_id=run_id,
+                session_id=session_id,
+                provider=provider_ref,
+                rollout=rollout,
+                error_code="recall_exception",
+                error_message=str(exc)[:200],
+                retryable=True,
+            ).to_dict()
+        ]

ksadk/studio/repository.py

@@ -109,7 +109,14 @@ class AgentDraftRepository:
             raise not_found("agent", agent_id)
         return self._read(path)
 
-    def update(self, agent_id: str, spec: AgentSpec, *, expected_revision: int) -> AgentDraft:
+    def update(
+        self,
+        agent_id: str,
+        spec: AgentSpec,
+        *,
+        expected_revision: int,
+        name: str | None = None,
+    ) -> AgentDraft:
         current = self.get(agent_id)
         if current.metadata.revision != expected_revision:
             raise StudioError(
@@ -124,6 +131,8 @@ class AgentDraftRepository:
             )
         updated = cast(AgentDraft, current.model_copy(deep=True))
         updated.metadata.revision += 1
+        if name is not None:
+            updated.metadata = updated.metadata.model_copy(update={"name": name})
         updated.spec = spec
         self._write(self._agent_file(agent_id), updated)
         return updated
@@ -245,7 +254,19 @@ class BuildRepository:
                 continue
             if record.agent_id == agent_id:
                 records.append(record)
-        return records
+        return sorted(records, key=lambda item: item.created_at, reverse=True)
+
+    def list(self) -> list[BuildRecord]:
+        records: list[BuildRecord] = []
+        directory = self.workspace.resolve(".agentkit/builds")
+        for path in directory.glob("build_*.json"):
+            try:
+                records.append(
+                    BuildRecord.model_validate_json(path.read_text(encoding="utf-8"))
+                )
+            except (OSError, ValidationError):
+                continue
+        return sorted(records, key=lambda item: item.created_at, reverse=True)
 
     def delete_for_agent(
         self,