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

ksadk/skills/runtime/base.py

@@ -5,13 +5,26 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Protocol, Sequence
 
+from ksadk.skills.events import SkillEvent, SkillInvocationPlan
 from ksadk.skills.package_store import SkillPackage
 
+_SANDBOX_OBSERVABILITY_ENV_PREFIXES = ("OTEL_", "LANGFUSE_")
+_SANDBOX_TRACE_ENV_NAMES = {"BAGGAGE", "TRACEPARENT", "TRACESTATE"}
+
 
 class SkillRuntimeError(RuntimeError):
     pass
 
 
+def sandbox_runtime_env(env: dict[str, str]) -> dict[str, str]:
+    return {
+        name: value
+        for name, value in env.items()
+        if not name.startswith(_SANDBOX_OBSERVABILITY_ENV_PREFIXES)
+        and name not in _SANDBOX_TRACE_ENV_NAMES
+    }
+
+
 @dataclass(frozen=True)
 class SandboxInputFile:
     source: Path
@@ -29,13 +42,20 @@ class SkillRuntimeResult:
     error_type: str | None = None
     error_message: str | None = None
     output_files: list[str] = field(default_factory=list)
+    output_text: str = ""
+    output_text_truncated: bool = False
+    skill_events: list[SkillEvent] = field(default_factory=list)
+    workflow_status: str = ""
+    executed_skill: str = ""
+    instructions: str = ""
+    sandbox: dict[str, object] = field(default_factory=dict)
 
     @property
     def ok(self) -> bool:
         return self.exit_code == 0 and not self.error_type and not self.timed_out
 
     def to_dict(self) -> dict[str, object]:
-        return {
+        result: dict[str, object] = {
             "runtime_id": self.runtime_id,
             "exit_code": self.exit_code,
             "stdout": self.stdout,
@@ -45,7 +65,19 @@ class SkillRuntimeResult:
             "error_type": self.error_type,
             "error_message": self.error_message,
             "output_files": list(self.output_files),
+            "workflow_status": self.workflow_status,
+            "executed_skill": self.executed_skill,
+            "instructions": self.instructions,
         }
+        if self.output_text:
+            result["output_text"] = self.output_text
+        if self.output_text_truncated:
+            result["output_text_truncated"] = True
+        if self.skill_events:
+            result["skill_events"] = [event.to_dict() for event in self.skill_events]
+        if self.sandbox:
+            result["sandbox"] = dict(self.sandbox)
+        return result
 
 
 class SkillRuntimeBackend(Protocol):
@@ -58,12 +90,26 @@ class SkillRuntimeBackend(Protocol):
         skill_names: list[str] | None = None,
         env: dict[str, str] | None = None,
         input_files: list[SandboxInputFile] | None = None,
+        invocation_plan: SkillInvocationPlan | None = None,
         pinned_packages: list[SkillPackage] | None = None,
         timeout: int = 900,
     ) -> SkillRuntimeResult: ...
 
 
-def parse_output_files(stdout: str) -> list[str]:
+@dataclass(frozen=True)
+class ParsedWorkflowResult:
+    output_files: tuple[str, ...] = ()
+    output_text: str = ""
+    output_text_truncated: bool = False
+    workflow_status: str = ""
+    executed_skill: str = ""
+    instructions: str = ""
+    error: str = ""
+    command_error_type: str = ""
+
+
+def parse_workflow_result(stdout: str) -> ParsedWorkflowResult:
+    """Parse the workflow_result= JSON line from agent.py stdout."""
     for line in stdout.splitlines():
         if not line.startswith("workflow_result="):
             continue
@@ -71,11 +117,36 @@ def parse_output_files(stdout: str) -> list[str]:
         try:
             payload = json.loads(raw)
         except json.JSONDecodeError:
-            return []
-        output_files = payload.get("output_files") if isinstance(payload, dict) else None
-        if isinstance(output_files, list):
-            return [str(item) for item in output_files]
-    return []
+            return ParsedWorkflowResult()
+        if not isinstance(payload, dict):
+            return ParsedWorkflowResult()
+        output_files = payload.get("output_files")
+        output_text = payload.get("output_text")
+        commands = payload.get("commands")
+        command_error_type = ""
+        if isinstance(commands, list):
+            for command in commands:
+                if isinstance(command, dict) and isinstance(command.get("error_type"), str):
+                    command_error_type = command["error_type"]
+                    break
+        return ParsedWorkflowResult(
+            output_files=(
+                tuple(str(item) for item in output_files) if isinstance(output_files, list) else ()
+            ),
+            output_text=output_text if isinstance(output_text, str) else "",
+            output_text_truncated=payload.get("output_text_truncated") is True,
+            workflow_status=str(payload.get("status") or ""),
+            executed_skill=str(payload.get("executed_skill") or ""),
+            instructions=str(payload.get("instructions") or ""),
+            error=str(payload.get("error") or ""),
+            command_error_type=command_error_type,
+        )
+    return ParsedWorkflowResult()
+
+
+def parse_output_files(stdout: str) -> list[str]:
+    """Compatibility helper for callers that only need artifact paths."""
+    return list(parse_workflow_result(stdout).output_files)
 
 
 def normalize_skill_names(skill_names: Sequence[str] | str | None) -> list[str]:

ksadk/skills/runtime/executor.py

@@ -4,12 +4,24 @@ import os
 import shutil
 import subprocess
 import tempfile
+import uuid
 from dataclasses import dataclass, field
 from pathlib import Path
 
+from ksadk.sandbox.local_controls import (
+    LocalControlSettings,
+    build_script_environment,
+    check_command,
+    controls_enabled,
+    resource_limit_reason,
+    run_bounded_process,
+)
+from ksadk.skills.events import SKILL_EVENT_FILE_ENV, SkillEvent, SkillEventSink
 from ksadk.skills.loader import LocalSkill
+from ksadk.skills.models import SkillRef
 from ksadk.skills.runtime.artifacts import (
     collect_output_dir_artifacts,
+    collect_text_output,
     merge_artifacts,
     parse_artifact_lines,
 )
@@ -21,12 +33,15 @@ class WorkflowExecution:
     status: str
     executed_skill: str = ""
     output_files: list[str] = field(default_factory=list)
+    output_text: str = ""
+    output_text_truncated: bool = False
     commands: list[dict[str, object]] = field(default_factory=list)
     selected_skills: list[str] = field(default_factory=list)
     loaded_skills: list[str] = field(default_factory=list)
     artifacts: list[str] = field(default_factory=list)
     warnings: list[str] = field(default_factory=list)
     error: str = ""
+    instructions: str = ""
     artifact_bundle: dict[str, object] | None = None
 
 
@@ -35,6 +50,9 @@ 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:
     selected = normalize_skill_names(selected_skill_names)
     loaded = [skill.name for skill in skills]
@@ -43,16 +61,39 @@ def execute_workflow(
 
     for skill in _candidate_skills(skills, selected):
         if _can_run_web_artifacts_builder(skill, prompt):
+            invocation_id, skill_ref = _execution_identity(skill, skill_refs, skill_invocation_ids)
+            _emit_execution(
+                event_sink, "skill.execution.started", "running", skill_ref, invocation_id
+            )
             result = _run_web_artifacts_builder(skill)
             _attach_context(result, selected=selected, loaded=loaded)
+            _emit_execution_result(event_sink, result, skill_ref, invocation_id)
             return result
 
     for skill in _candidate_skills(skills, selected):
         if _can_run_generic_workflow(skill):
+            invocation_id, skill_ref = _execution_identity(skill, skill_refs, skill_invocation_ids)
+            _emit_execution(
+                event_sink, "skill.execution.started", "running", skill_ref, invocation_id
+            )
             result = _run_generic_workflow(skill, prompt)
             _attach_context(result, selected=selected, loaded=loaded)
+            _emit_execution_result(event_sink, result, skill_ref, invocation_id)
             return result
 
+    for skill in _candidate_skills(skills, selected):
+        invocation_id, skill_ref = _execution_identity(skill, skill_refs, skill_invocation_ids)
+        if _has_instructions(skill):
+            _emit_execution(
+                event_sink, "skill.execution.started", "running", skill_ref, invocation_id
+            )
+            result = _run_instruction_only(skill, prompt)
+            _attach_context(result, selected=selected, loaded=loaded)
+            _emit_execution_result(event_sink, result, skill_ref, invocation_id)
+            return result
+        _emit_execution(
+            event_sink, "skill.execution.completed", "skipped", skill_ref, invocation_id
+        )
     return WorkflowExecution(
         status="skipped",
         selected_skills=selected,
@@ -73,6 +114,85 @@ def _attach_context(result: WorkflowExecution, *, selected: list[str], loaded: l
     result.loaded_skills = loaded
     if not result.artifacts:
         result.artifacts = list(result.output_files)
+    result.output_text, result.output_text_truncated = collect_text_output(
+        result.artifacts,
+        allowed_root=_skill_workdir(),
+        max_bytes=_output_text_limit(),
+    )
+
+
+def _execution_identity(
+    skill: LocalSkill,
+    skill_refs: dict[str, SkillRef] | None,
+    skill_invocation_ids: dict[str, str] | None,
+) -> tuple[str, SkillRef | None]:
+    skill_ref = (skill_refs or {}).get(skill.name)
+    invocation_id = (skill_invocation_ids or {}).get(skill.name) or f"skill_inv_{uuid.uuid4().hex}"
+    return invocation_id, skill_ref
+
+
+def _emit_execution(
+    event_sink: SkillEventSink | None,
+    event_type: str,
+    status: str,
+    skill_ref: SkillRef | None,
+    invocation_id: str,
+    *,
+    error_category: str = "",
+) -> None:
+    if event_sink is not None:
+        event_sink.emit(
+            SkillEvent.create(
+                event_type,
+                status=status,
+                skill_ref=skill_ref,
+                skill_invocation_id=invocation_id,
+                error_category=error_category,
+            )
+        )
+
+
+def _emit_execution_result(
+    event_sink: SkillEventSink | None,
+    result: WorkflowExecution,
+    skill_ref: SkillRef | None,
+    invocation_id: str,
+) -> None:
+    status = "failed" if result.status in ("failed", "error") else "completed"
+    error_category = ""
+    if any(command.get("timed_out") for command in result.commands):
+        error_category = "timeout"
+    elif any(command.get("status") == "blocked" for command in result.commands):
+        error_category = "safety_policy"
+    elif any(command.get("output_limit_exceeded") for command in result.commands):
+        error_category = "output_limit"
+    elif any(command.get("resource_limit") for command in result.commands):
+        error_category = "resource_limit"
+    _emit_execution(
+        event_sink,
+        f"skill.execution.{status}",
+        status,
+        skill_ref,
+        invocation_id,
+        error_category=error_category,
+    )
+    if event_sink is None:
+        return
+    for index, artifact in enumerate(result.artifacts):
+        artifact_path = Path(artifact)
+        event_sink.emit(
+            SkillEvent.create(
+                "skill.artifact.created",
+                status="completed",
+                skill_ref=skill_ref,
+                skill_invocation_id=invocation_id,
+                attributes={
+                    "artifact_ref": f"{invocation_id}:{index}",
+                    "artifact_name": artifact_path.name,
+                    "size_bytes": artifact_path.stat().st_size if artifact_path.exists() else 0,
+                },
+            )
+        )
 
 
 def _can_run_web_artifacts_builder(skill: LocalSkill, prompt: str) -> bool:
@@ -93,6 +213,23 @@ def _can_run_generic_workflow(skill: LocalSkill) -> bool:
     return (skill.root_dir / "scripts" / "run-workflow.sh").exists()
 
 
+def _has_instructions(skill: LocalSkill) -> bool:
+    has_scripts = (skill.root_dir / "scripts").is_dir()
+    return not has_scripts and bool(skill.body and skill.body.strip())
+
+
+def _run_instruction_only(skill: LocalSkill, prompt: str) -> WorkflowExecution:
+    return WorkflowExecution(
+        status="instructions",
+        executed_skill=skill.name,
+        instructions=skill.body,
+        warnings=[
+            "This skill is instruction-only (no executable scripts). "
+            "Follow the instructions below using your available tools."
+        ],
+    )
+
+
 def _run_web_artifacts_builder(skill: LocalSkill) -> WorkflowExecution:
     workdir = _skill_workdir()
     project_name = _safe_project_name(
@@ -101,6 +238,24 @@ def _run_web_artifacts_builder(skill: LocalSkill) -> WorkflowExecution:
     project_dir = workdir / project_name
     workdir.mkdir(parents=True, exist_ok=True)
     if project_dir.exists():
+        if project_dir.is_symlink() or project_dir.resolve().parent != workdir.resolve():
+            return WorkflowExecution(
+                status="failed",
+                executed_skill=skill.name,
+                commands=[
+                    {
+                        "command": "prepare artifact project",
+                        "cwd": str(workdir),
+                        "exit_code": 126,
+                        "status": "blocked",
+                        "error_type": "SafetyPolicyViolation",
+                        "blocked_reason": (
+                            "path.project_directory_boundary: existing artifact project path "
+                            "must be a real directory directly inside the Skill workdir"
+                        ),
+                    }
+                ],
+            )
         shutil.rmtree(project_dir)
 
     timeout = _runtime_timeout()
@@ -109,15 +264,22 @@ def _run_web_artifacts_builder(skill: LocalSkill) -> WorkflowExecution:
         ["bash", str(skill.root_dir / "scripts" / "init-artifact.sh"), project_name],
         cwd=workdir,
         timeout=timeout,
+        allowed_roots=(workdir, skill.root_dir),
     )
     commands.append(init_result)
     if init_result["exit_code"] != 0:
-        return WorkflowExecution(status="failed", executed_skill=skill.name, commands=commands)
+        return WorkflowExecution(
+            status="failed",
+            executed_skill=skill.name,
+            commands=commands,
+            error=_command_error(init_result),
+        )
 
     bundle_result = _run_command(
         ["bash", str(skill.root_dir / "scripts" / "bundle-artifact.sh")],
         cwd=project_dir,
         timeout=timeout,
+        allowed_roots=(workdir, skill.root_dir),
     )
     commands.append(bundle_result)
     output_files = (
@@ -130,6 +292,7 @@ def _run_web_artifacts_builder(skill: LocalSkill) -> WorkflowExecution:
         output_files=output_files,
         artifacts=list(output_files),
         commands=commands,
+        error=_command_error(bundle_result) if status == "failed" else "",
     )
 
 
@@ -143,6 +306,7 @@ def _run_generic_workflow(skill: LocalSkill, prompt: str) -> WorkflowExecution:
         ["bash", str(skill.root_dir / "scripts" / "run-workflow.sh")],
         cwd=workdir,
         timeout=timeout,
+        allowed_roots=(workdir, skill.root_dir),
         extra_env={
             "KSADK_WORKFLOW_PROMPT": prompt,
             "KSADK_SKILL_WORKDIR": str(workdir),
@@ -161,6 +325,7 @@ def _run_generic_workflow(skill: LocalSkill, prompt: str) -> WorkflowExecution:
         output_files=list(artifacts),
         artifacts=list(artifacts),
         commands=[command],
+        error=_command_error(command) if status == "failed" else "",
     )
 
 
@@ -177,8 +342,18 @@ def _run_command(
     cwd: Path,
     timeout: int,
     extra_env: dict[str, str] | None = None,
+    allowed_roots: tuple[Path, ...] | None = None,
 ) -> dict[str, object]:
+    if controls_enabled():
+        return _run_controlled_command(
+            args,
+            cwd=cwd,
+            timeout=timeout,
+            extra_env=extra_env,
+            allowed_roots=allowed_roots or (cwd,),
+        )
     env = os.environ.copy()
+    env.pop(SKILL_EVENT_FILE_ENV, None)
     env.setdefault("CI", "1")
     env.update(extra_env or {})
     try:
@@ -209,6 +384,79 @@ def _run_command(
         }
 
 
+def _run_controlled_command(
+    args: list[str],
+    *,
+    cwd: Path,
+    timeout: int,
+    extra_env: dict[str, str] | None,
+    allowed_roots: tuple[Path, ...],
+) -> dict[str, object]:
+    command_text = " ".join(args)
+    try:
+        settings = LocalControlSettings.from_runtime_env()
+    except (TypeError, ValueError) as exc:
+        return {
+            "command": command_text,
+            "cwd": str(cwd),
+            "exit_code": 125,
+            "status": "failed",
+            "error_type": "LocalControlConfigurationError",
+            "error_message": str(exc),
+            "controls": {"status": "failed"},
+        }
+    finding = check_command(args, cwd=cwd, allowed_roots=allowed_roots)
+    if finding is not None:
+        return {
+            "command": command_text,
+            "cwd": str(cwd),
+            "exit_code": 126,
+            "status": "blocked",
+            "error_type": "SafetyPolicyViolation",
+            "blocked_reason": finding.reason(),
+            "controls": {"status": "blocked", "static_check": finding.rule},
+        }
+    required = dict(extra_env or {})
+    required.setdefault("TMPDIR", str(cwd))
+    env = build_script_environment(os.environ, settings=settings, required=required)
+    executed = run_bounded_process(
+        args,
+        cwd=cwd,
+        env=env,
+        timeout=min(timeout, settings.wall_seconds),
+        settings=settings,
+        # The outer local runtime owns the process group and always cleans it.
+        # Starting a nested session here would let commands outlive outer timeout.
+        start_new_session=False,
+    )
+    result: dict[str, object] = {
+        "command": command_text,
+        "cwd": str(cwd),
+        "exit_code": executed.exit_code,
+        "stdout": executed.stdout,
+        "stderr": executed.stderr,
+        "controls": executed.controls,
+        "cleanup_status": "deferred_to_runtime_process_group",
+    }
+    if executed.timed_out:
+        result.update(timed_out=True, status="failed", error_type="TimeoutExpired")
+    if executed.output_limit_exceeded:
+        result.update(
+            status="failed",
+            error_type="OutputLimitExceeded",
+            output_limit_exceeded=True,
+        )
+    if executed.stdout_truncated:
+        result["stdout_truncated"] = True
+    if executed.stderr_truncated:
+        result["stderr_truncated"] = True
+    if executed.controls.get("status") == "failed":
+        result.update(status="failed", error_type="ResourceLimitSetupError")
+    if limit := resource_limit_reason(executed.exit_code):
+        result.update(status="failed", error_type="ResourceLimitExceeded", resource_limit=limit)
+    return result
+
+
 def _runtime_timeout() -> int:
     try:
         return int(os.environ.get("KSADK_SKILL_RUNTIME_TIMEOUT", "900"))
@@ -216,6 +464,23 @@ def _runtime_timeout() -> int:
         return 900
 
 
+def _command_error(command: dict[str, object]) -> str:
+    return str(
+        command.get("blocked_reason")
+        or command.get("error_message")
+        or command.get("error_type")
+        or "Skill command failed"
+    )
+
+
+def _output_text_limit() -> int:
+    try:
+        configured = int(os.environ.get("KSADK_SKILL_OUTPUT_TEXT_MAX_BYTES", "65536"))
+    except ValueError:
+        configured = 65536
+    return min(max(configured, 0), 1024 * 1024)
+
+
 def _safe_project_name(raw: str) -> str:
     sanitized = "".join(ch if ch.isalnum() or ch in {"-", "_"} else "-" for ch in raw).strip("-_")
     return sanitized[:80] or "ksadk-artifact"

ksadk/skills/runtime/loader.py

@@ -3,11 +3,14 @@ from __future__ import annotations
 import os
 import shutil
 import tempfile
+import time
+import uuid
 from dataclasses import dataclass, field
 from pathlib import Path
 
 import httpx
 
+from ksadk.skills.events import SkillEvent, SkillEventSink
 from ksadk.skills.loader import LocalSkill, load_local_skill
 from ksadk.skills.models import SkillRef
 from ksadk.skills.package_store import PackageStore, SkillPackageError
@@ -20,6 +23,8 @@ from ksadk.skills.service_env import resolve_skill_service_url
 class SkillLoadResult:
     skills: list[LocalSkill] = field(default_factory=list)
     warnings: list[str] = field(default_factory=list)
+    skill_refs: dict[str, SkillRef] = field(default_factory=dict)
+    skill_invocation_ids: dict[str, str] = field(default_factory=dict)
 
 
 def load_skills(
@@ -27,6 +32,8 @@ def load_skills(
     prompt: str = "",
     skill_names: list[str] | None = None,
     service_transport: httpx.BaseTransport | None = None,
+    event_sink: SkillEventSink | None = None,
+    planned_invocations: dict[str, str] | None = None,
 ) -> SkillLoadResult:
     warnings: list[str] = []
     skills: list[LocalSkill] = []
@@ -77,19 +84,90 @@ def load_skills(
             )
         )
 
+    skill_refs: dict[str, SkillRef] = {}
+    skill_invocation_ids: dict[str, str] = {}
     for skill in selected_refs:
+        if planned_invocations is not None and skill.skill_id not in planned_invocations:
+            continue
+        invocation_id = (planned_invocations or {}).get(skill.skill_id)
+        invocation_id = invocation_id or f"skill_inv_{uuid.uuid4().hex}"
         package = store.get_cached(skill)
         if package is None:
+            downloaded_at = time.time()
             archive = client.download_skill_archive(skill)
+            _emit(
+                event_sink,
+                "skill.package.downloaded",
+                skill_ref=skill,
+                skill_invocation_id=invocation_id,
+                status="completed",
+                started_at=downloaded_at,
+                ended_at=time.time(),
+            )
             try:
-                package = store.store_archive(skill, archive)
+                package = store.store_archive(
+                    skill,
+                    archive,
+                    event_sink=event_sink,
+                    skill_invocation_id=invocation_id,
+                )
             except SkillPackageError as exc:
                 if not _allow_hash_mismatch():
                     raise
                 package = _store_unverified_archive(store, skill, archive)
                 warnings.append(str(exc))
-        skills.append(load_local_skill(package.root_dir))
-    return SkillLoadResult(skills=skills, warnings=warnings)
+        else:
+            _emit(
+                event_sink,
+                "skill.package.cache_hit",
+                skill_ref=skill,
+                skill_invocation_id=invocation_id,
+                status="completed",
+                attributes={"cache_hit": True},
+            )
+        _emit(
+            event_sink,
+            "skill.load.started",
+            skill_ref=skill,
+            skill_invocation_id=invocation_id,
+            status="running",
+        )
+        try:
+            local_skill = load_local_skill(package.root_dir)
+        except Exception as exc:
+            _emit(
+                event_sink,
+                "skill.load.failed",
+                skill_ref=skill,
+                skill_invocation_id=invocation_id,
+                status="failed",
+                error_category=type(exc).__name__,
+            )
+            raise
+        _emit(
+            event_sink,
+            "skill.manifest.parsed",
+            skill_ref=skill,
+            skill_invocation_id=invocation_id,
+            status="completed",
+            attributes={"has_description": bool(local_skill.description)},
+        )
+        _emit(
+            event_sink,
+            "skill.load.completed",
+            skill_ref=skill,
+            skill_invocation_id=invocation_id,
+            status="completed",
+        )
+        skills.append(local_skill)
+        skill_refs[local_skill.name] = skill
+        skill_invocation_ids[local_skill.name] = invocation_id
+    return SkillLoadResult(
+        skills=skills,
+        warnings=warnings,
+        skill_refs=skill_refs,
+        skill_invocation_ids=skill_invocation_ids,
+    )
 
 
 def load_local_skills() -> list[LocalSkill]:
@@ -115,6 +193,33 @@ def _allow_hash_mismatch() -> bool:
     }
 
 
+def _emit(
+    event_sink: SkillEventSink | None,
+    event_type: str,
+    *,
+    status: str,
+    skill_ref: SkillRef | None = None,
+    skill_invocation_id: str = "",
+    attributes: dict[str, object] | None = None,
+    error_category: str = "",
+    started_at: float | None = None,
+    ended_at: float | None = None,
+) -> None:
+    if event_sink is not None:
+        event_sink.emit(
+            SkillEvent.create(
+                event_type,
+                status=status,
+                skill_ref=skill_ref,
+                skill_invocation_id=skill_invocation_id,
+                attributes=attributes,
+                error_category=error_category,
+                started_at=started_at,
+                ended_at=ended_at,
+            )
+        )
+
+
 def _store_unverified_archive(store: PackageStore, skill: SkillRef, archive: bytes):
     skill_dir = store.cache_dir / f"unverified-{skill.cache_key or skill.name or 'skill'}"
     if skill_dir.exists():