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

ksadk/skills/observability.py

@@ -0,0 +1,132 @@
+"""OTEL projection for typed Skill Runtime facts."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+from ksadk.skills.events import SkillEvent
+
+_LIFECYCLE_STARTS = {
+    "skill.load.started": "skill.load",
+    "skill.execution.started": "skill.execution",
+    "sandbox.session.created": "sandbox.session",
+}
+_LIFECYCLE_ENDS = {
+    "skill.load.completed": "skill.load",
+    "skill.load.failed": "skill.load",
+    "skill.execution.completed": "skill.execution",
+    "skill.execution.failed": "skill.execution",
+    "sandbox.session.cleaned_up": "sandbox.session",
+    "sandbox.session.cleanup_failed": "sandbox.session",
+}
+
+
+def project_skill_events(events: Iterable[SkillEvent], *, tracer: Any | None = None) -> None:
+    """Project facts beneath the current tool span without affecting execution."""
+
+    try:
+        from opentelemetry import trace
+        from opentelemetry.trace import Status, StatusCode
+
+        active_tracer = tracer or trace.get_tracer("ksadk.skills")
+        parent = trace.get_current_span()
+        lifecycle_starts: dict[tuple[str, str], SkillEvent] = {}
+        for event in events:
+            attributes = _span_attributes(event)
+            lifecycle = _LIFECYCLE_STARTS.get(event.event_type)
+            if lifecycle:
+                lifecycle_starts[(lifecycle, _lifecycle_id(event))] = event
+                continue
+            lifecycle = _LIFECYCLE_ENDS.get(event.event_type)
+            if lifecycle:
+                start = lifecycle_starts.pop((lifecycle, _lifecycle_id(event)), event)
+                _project_span(
+                    active_tracer,
+                    event,
+                    attributes,
+                    start.started_at,
+                    event.started_at,
+                    Status,
+                    StatusCode,
+                )
+            elif event.ended_at is not None:
+                _project_span(
+                    active_tracer,
+                    event,
+                    attributes,
+                    event.started_at,
+                    event.ended_at,
+                    Status,
+                    StatusCode,
+                )
+            elif parent.is_recording():
+                parent.add_event(
+                    event.event_type,
+                    attributes=attributes,
+                    timestamp=_nanoseconds(event.started_at),
+                )
+    except Exception:
+        return
+
+
+def _project_span(
+    tracer: Any,
+    event: SkillEvent,
+    attributes: dict[str, str | int | float | bool | list[str]],
+    started_at: float,
+    ended_at: float,
+    Status: Any,
+    StatusCode: Any,
+) -> None:
+    span = tracer.start_span(event.event_type, start_time=_nanoseconds(started_at))
+    for key, value in attributes.items():
+        span.set_attribute(key, value)
+    if event.status in {"failed", "timeout", "timed_out", "cleanup_failed"}:
+        span.set_status(Status(StatusCode.ERROR, event.error_category or event.status))
+    span.end(end_time=_nanoseconds(ended_at))
+
+
+def _lifecycle_id(event: SkillEvent) -> str:
+    return event.skill_invocation_id or event.runtime_id
+
+
+def _span_attributes(event: SkillEvent) -> dict[str, str | int | float | bool | list[str]]:
+    attributes: dict[str, str | int | float | bool | list[str]] = {
+        "ksadk.skill.event_type": event.event_type,
+        "ksadk.skill.status": event.status,
+    }
+    for name, value in (
+        ("event_id", event.event_id),
+        ("invocation_id", event.skill_invocation_id),
+        ("runtime_id", event.runtime_id),
+        ("run_id", event.run_id),
+        ("binding_snapshot_id", event.binding_snapshot_id),
+        ("decision_id", event.decision_id),
+        ("error_code", event.error_code),
+        ("error_category", event.error_category),
+    ):
+        if value:
+            attributes[f"ksadk.skill.{name}"] = value
+    if event.skill_ref is not None:
+        attributes["ksadk.skill.id"] = event.skill_ref.skill_id
+        attributes["ksadk.skill.version_id"] = event.skill_ref.version_id
+        attributes["ksadk.skill.version"] = event.skill_ref.version
+        attributes["ksadk.skill.name"] = event.skill_ref.name
+    for key, value in event.attributes.items():
+        normalized = _attribute_value(value)
+        if normalized is not None:
+            attributes[f"ksadk.skill.{key}"] = normalized
+    return attributes
+
+
+def _attribute_value(value: Any) -> str | int | float | bool | list[str] | None:
+    if isinstance(value, (str, int, float, bool)):
+        return value
+    if isinstance(value, (list, tuple)) and all(isinstance(item, str) for item in value):
+        return list(value)
+    return None
+
+
+def _nanoseconds(timestamp: float) -> int:
+    return int(timestamp * 1_000_000_000)

ksadk/skills/package_store.py

@@ -7,6 +7,7 @@ import shutil
 import stat
 import tempfile
 import threading
+import time
 import zipfile
 from contextlib import contextmanager
 from dataclasses import dataclass
@@ -17,6 +18,7 @@ try:
 except ImportError:  # Windows legacy callers retain in-process synchronization.
     fcntl = None
 
+from ksadk.skills.events import SkillEvent, SkillEventSink
 from ksadk.skills.models import SkillRef
 
 
@@ -60,14 +62,43 @@ class PackageStore:
         self.max_files = max_files
         self._thread_lock = threading.RLock()
 
-    def store_archive(self, ref: SkillRef, content: bytes) -> SkillPackage:
-        self._verify_hash(ref, content)
+    def store_archive(
+        self,
+        ref: SkillRef,
+        content: bytes,
+        *,
+        event_sink: SkillEventSink | None = None,
+        skill_invocation_id: str = "",
+    ) -> SkillPackage:
+        hash_started_at = time.time()
+        try:
+            self._verify_hash(ref, content)
+        except SkillPackageError:
+            self._emit_lifecycle(
+                event_sink,
+                "skill.package.hash_verified",
+                status="failed",
+                ref=ref,
+                skill_invocation_id=skill_invocation_id,
+                started_at=hash_started_at,
+                error_category="hash_verification_failed",
+            )
+            raise
+        self._emit_lifecycle(
+            event_sink,
+            "skill.package.hash_verified",
+            status="completed",
+            ref=ref,
+            skill_invocation_id=skill_invocation_id,
+            started_at=hash_started_at,
+        )
         with self._locked(ref):
             cached = self._get_cached(ref)
             if cached is not None:
                 return cached
             skill_dir = self._skill_dir(ref)
             stage = Path(tempfile.mkdtemp(prefix=".stage-", dir=self.cache_dir))
+            extract_started_at = time.time()
             try:
                 (stage / "archive.zip").write_bytes(content)
                 os.chmod(stage / "archive.zip", 0o600)
@@ -82,10 +113,27 @@ class PackageStore:
                     shutil.rmtree(skill_dir)
                 os.replace(stage, skill_dir)
             except (OSError, zipfile.BadZipFile, RuntimeError, ValueError) as error:
+                self._emit_lifecycle(
+                    event_sink,
+                    "skill.package.extracted",
+                    status="failed",
+                    ref=ref,
+                    skill_invocation_id=skill_invocation_id,
+                    started_at=extract_started_at,
+                    error_category="extract_failed",
+                )
                 raise SkillPackageError("Skill archive could not be safely materialized") from error
             finally:
                 if stage.exists():
                     shutil.rmtree(stage)
+            self._emit_lifecycle(
+                event_sink,
+                "skill.package.extracted",
+                status="completed",
+                ref=ref,
+                skill_invocation_id=skill_invocation_id,
+                started_at=extract_started_at,
+            )
             return self._package(ref, skill_dir, cache_hit=False)
 
     def get_cached(self, ref: SkillRef) -> SkillPackage | None:
@@ -253,3 +301,28 @@ class PackageStore:
         if not candidates:
             raise SkillPackageError(f"SKILL.md not found under {extract_dir}")
         return candidates[0]
+
+    @staticmethod
+    def _emit_lifecycle(
+        event_sink: SkillEventSink | None,
+        event_type: str,
+        *,
+        status: str,
+        ref: SkillRef,
+        skill_invocation_id: str,
+        started_at: float,
+        error_category: str = "",
+    ) -> None:
+        if event_sink is None or not skill_invocation_id:
+            return
+        event_sink.emit(
+            SkillEvent.create(
+                event_type,
+                status=status,
+                skill_ref=ref,
+                skill_invocation_id=skill_invocation_id,
+                started_at=started_at,
+                ended_at=time.time(),
+                error_category=error_category,
+            )
+        )

ksadk/skills/runtime/agent.py

@@ -8,6 +8,7 @@ from pathlib import Path
 
 import httpx
 
+from ksadk.skills.events import SKILL_EVENT_FILE_ENV, SkillEventSink
 from ksadk.skills.loader import LocalSkill
 from ksadk.skills.models import SkillRef
 from ksadk.skills.package_store import PackageStore
@@ -74,14 +75,18 @@ def _load_skills(
     prompt: str = "",
     skill_names: list[str] | None = None,
     service_transport: httpx.BaseTransport | None = None,
-) -> list[LocalSkill]:
+    event_sink: SkillEventSink | None = None,
+    planned_invocations: dict[str, str] | None = None,
+) -> runtime_loader.SkillLoadResult:
     result = runtime_loader.load_skills(
         prompt=prompt,
         skill_names=skill_names,
         service_transport=service_transport,
+        event_sink=event_sink,
+        planned_invocations=planned_invocations,
     )
     _SKILL_LOAD_WARNINGS.extend(result.warnings)
-    return result.skills
+    return result
 
 
 def _dedupe_skill_refs(skill_refs: list[SkillRef], *, seen_names: set[str]) -> list[SkillRef]:
@@ -134,18 +139,36 @@ def run_agent(
 
     prompt = request.workflow_prompt
     selected_skill_names = request.skill_names
+    event_sink = SkillEventSink(os.environ.get(SKILL_EVENT_FILE_ENV))
+    planned_invocations = {
+        entry["skill_id"]: entry["skill_invocation_id"] for entry in request.invocation_plan
+    }
     if request.pinned_packages is not None:
         if request.package_directory is None:
             raise SkillWorkflowRequestError("Pinned Skill delivery directory is missing")
         loaded_skills = load_pinned_packages(request.pinned_packages, request.package_directory)
+        skill_refs = None
+        skill_invocation_ids = None
     else:
         selected_skill_names = selected_skill_names or _selected_skill_names()
-        loaded_skills = _load_skills(
+        load_result = _load_skills(
             prompt=prompt,
             skill_names=selected_skill_names,
             service_transport=service_transport,
+            event_sink=event_sink,
+            planned_invocations=planned_invocations or None,
         )
-    execution = _execute_workflow(prompt, loaded_skills, selected_skill_names=selected_skill_names)
+        loaded_skills = load_result.skills
+        skill_refs = load_result.skill_refs
+        skill_invocation_ids = load_result.skill_invocation_ids
+    execution = _execute_workflow(
+        prompt,
+        loaded_skills,
+        selected_skill_names=selected_skill_names,
+        event_sink=event_sink,
+        skill_refs=skill_refs,
+        skill_invocation_ids=skill_invocation_ids,
+    )
     if request.collect_artifacts and request.package_directory is not None:
         try:
             root = Path(os.environ.get("KSADK_SKILL_WORKDIR") or "/tmp/ksadk-skill-workflow")
@@ -183,8 +206,18 @@ def _execute_workflow(
     skills: list[LocalSkill],
     *,
     selected_skill_names: list[str] | None = None,
+    event_sink: SkillEventSink | None = None,
+    skill_refs: dict[str, SkillRef] | None = None,
+    skill_invocation_ids: dict[str, str] | None = None,
 ) -> WorkflowExecution:
-    return execute_workflow(prompt, skills, selected_skill_names=selected_skill_names)
+    return execute_workflow(
+        prompt,
+        skills,
+        selected_skill_names=selected_skill_names,
+        event_sink=event_sink,
+        skill_refs=skill_refs,
+        skill_invocation_ids=skill_invocation_ids,
+    )
 
 
 def _can_run_web_artifacts_builder(skill: LocalSkill, prompt: str) -> bool:

ksadk/skills/runtime/artifacts.py

@@ -2,6 +2,22 @@ from __future__ import annotations
 
 from pathlib import Path
 
+TEXT_ARTIFACT_SUFFIXES = frozenset(
+    {
+        ".csv",
+        ".json",
+        ".jsonl",
+        ".log",
+        ".md",
+        ".rst",
+        ".tsv",
+        ".txt",
+        ".xml",
+        ".yaml",
+        ".yml",
+    }
+)
+
 
 def parse_artifact_lines(stdout: str) -> list[str]:
     artifacts: list[str] = []
@@ -33,3 +49,74 @@ def merge_artifacts(*groups: list[str]) -> list[str]:
             seen.add(item)
             merged.append(item)
     return merged
+
+
+def collect_text_output(
+    artifacts: list[str],
+    *,
+    allowed_root: Path,
+    max_bytes: int,
+) -> tuple[str, bool]:
+    """Read bounded text artifacts without escaping the Skill workdir.
+
+    Artifact paths are controlled by the executed Skill, so only regular,
+    non-symlink text files contained by ``allowed_root`` are eligible. Binary
+    artifacts remain available through artifact metadata and are never placed
+    in the model-facing result.
+    """
+
+    root = allowed_root.resolve()
+    candidates: list[Path] = []
+    seen: set[Path] = set()
+    for raw_path in artifacts:
+        path = Path(raw_path)
+        if not path.is_absolute():
+            path = root / path
+        try:
+            if path.is_symlink():
+                continue
+            resolved = path.resolve(strict=True)
+            resolved.relative_to(root)
+        except (FileNotFoundError, OSError, ValueError):
+            continue
+        if (
+            resolved in seen
+            or not resolved.is_file()
+            or resolved.suffix.lower() not in TEXT_ARTIFACT_SUFFIXES
+        ):
+            continue
+        seen.add(resolved)
+        candidates.append(resolved)
+
+    budget = max(0, max_bytes)
+    if not candidates or budget == 0:
+        return "", bool(candidates)
+
+    chunks: list[str] = []
+    truncated = False
+    include_headers = len(candidates) > 1
+    for index, path in enumerate(candidates):
+        separator = "\n\n" if index else ""
+        header = f"--- {path.name} ---\n" if include_headers else ""
+        prefix = separator + header
+        prefix_bytes = prefix.encode("utf-8")
+        if len(prefix_bytes) >= budget:
+            truncated = True
+            break
+
+        try:
+            with path.open("rb") as stream:
+                payload = stream.read(budget - len(prefix_bytes) + 1)
+        except OSError:
+            continue
+        budget -= len(prefix_bytes)
+        if len(payload) > budget:
+            payload = payload[:budget]
+            truncated = True
+        chunks.append(prefix + payload.decode("utf-8", errors="replace"))
+        budget -= len(payload)
+        if truncated or budget == 0:
+            truncated = truncated or index < len(candidates) - 1
+            break
+
+    return "".join(chunks), truncated