@openlucaskaka/kagent 0.1.7

package/src/kagent/service/runtime_approval.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def validate_approved_action_ids(value: Any) -> tuple[list[str], str]:
+    if not isinstance(value, list) or any(not isinstance(item, str) for item in value):
+        return [], "approved_action_ids must be an array of strings"
+    seen = set()
+    approved_action_ids = []
+    for action_id in value:
+        if not action_id.strip():
+            return [], "approved_action_ids must contain non-empty strings"
+        if action_id != action_id.strip():
+            return [], "approved_action_ids must not contain surrounding whitespace"
+        if action_id in seen:
+            return [], "approved_action_ids must not contain duplicate action ids"
+        seen.add(action_id)
+        approved_action_ids.append(action_id)
+    return approved_action_ids, ""

package/src/kagent/service/runtime_cancel.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from typing import Any, Dict, Tuple
+
+from kagent.service import errors as service_errors
+from kagent.service.active_runs import ActiveRunRegistry, ActiveRunSnapshot
+from kagent.service.errors import failure_payload
+from kagent.service.runtime import ServiceConfig
+from kagent.service.runtime_lifecycle import persist_cancelled_runtime_trace
+from kagent.service.runtime_status import (
+    is_runtime_trace,
+    runtime_status_summary,
+)
+from kagent.service.trace_store import (
+    load_trace_by_run_id,
+)
+from kagent.utils.json_output import json_ready
+
+_TRACE_READ_ERRORS = (OSError, ValueError)
+_TERMINAL_RUNTIME_STATUSES = {"cancelled", "done", "failed", "resumed"}
+MAX_CANCEL_REASON_CHARS = 500
+
+
+def execute_runtime_cancel_request(
+    run_id: str,
+    body: bytes,
+    service_config: ServiceConfig,
+    auth_subject: str = "",
+    *,
+    request_auth_is_admin: bool = False,
+    active_run_registry: ActiveRunRegistry | None = None,
+) -> Tuple[int, Dict[str, Any]]:
+    if not service_config.trace_dir:
+        return 400, failure_payload(
+            service_errors.INVALID_AGENT_CONFIG,
+            "trace_dir is required for runtime cancel",
+        )
+    if not run_id.strip():
+        return 400, failure_payload(service_errors.INVALID_REQUEST_BODY, "run_id is required")
+    try:
+        payload = json.loads(body.decode("utf-8") or "{}")
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        return 400, failure_payload(service_errors.INVALID_JSON, f"invalid JSON: {exc}")
+    if not isinstance(payload, dict):
+        return 400, failure_payload(
+            service_errors.INVALID_REQUEST_BODY,
+            "request body must be a JSON object",
+        )
+    if set(payload) - {"reason"}:
+        return 400, failure_payload(
+            service_errors.INVALID_REQUEST_BODY,
+            "cancel request only accepts an optional reason field",
+        )
+    reason = payload.get("reason", "")
+    if not isinstance(reason, str):
+        return 400, failure_payload(
+            service_errors.INVALID_REQUEST_BODY,
+            "reason must be a string",
+        )
+    reason = reason.strip()
+    if len(reason) > MAX_CANCEL_REASON_CHARS:
+        return 400, failure_payload(
+            service_errors.INVALID_REQUEST_BODY,
+            f"reason must be at most {MAX_CANCEL_REASON_CHARS} characters",
+        )
+
+    try:
+        trace = load_trace_by_run_id(run_id, service_config.trace_dir)
+    except _TRACE_READ_ERRORS:
+        return 500, failure_payload(
+            service_errors.TRACE_READ_FAILED,
+            "runtime run trace could not be read",
+        )
+    if trace is None or not is_runtime_trace(trace):
+        return 404, failure_payload(service_errors.NOT_FOUND, "runtime run trace not found")
+    owner_auth_subject = str(trace.get("auth_subject", "")) or auth_subject
+    if auth_subject and not request_auth_is_admin and owner_auth_subject != auth_subject:
+        return 404, failure_payload(service_errors.NOT_FOUND, "runtime run trace not found")
+    if active_run_registry is not None:
+        active_run = active_run_registry.request_cancel(
+            run_id,
+            requested_by_auth_subject=auth_subject,
+            request_auth_is_admin=request_auth_is_admin,
+            reason=reason,
+        )
+        if active_run is not None:
+            if active_run.state != "cancelled":
+                return 409, failure_payload(
+                    service_errors.INVALID_REQUEST_BODY,
+                    "runtime run is already terminal",
+                )
+            try:
+                cancelled_trace = persist_cancelled_runtime_trace(
+                    run_id=run_id,
+                    trace_dir=service_config.trace_dir,
+                    active_run=active_run,
+                    cancelled_by_auth_subject=auth_subject,
+                )
+            except (OSError, ValueError) as exc:
+                return 500, failure_payload(
+                    service_errors.TRACE_PERSISTENCE_FAILED,
+                    f"could not persist trace: {exc}",
+                )
+            persisted_status = str(cancelled_trace.get("status", ""))
+            if persisted_status == "resuming":
+                return 409, failure_payload(
+                    service_errors.INVALID_REQUEST_BODY,
+                    "runtime run approval is being resumed",
+                )
+            if persisted_status != "cancelled":
+                return 409, failure_payload(
+                    service_errors.INVALID_REQUEST_BODY,
+                    "runtime run is already terminal",
+                )
+            return 200, json_ready(
+                runtime_status_summary(
+                    cancelled_trace,
+                    service_config.trace_dir,
+                    run_id,
+                )
+            )
+        try:
+            refreshed_trace = load_trace_by_run_id(run_id, service_config.trace_dir)
+        except _TRACE_READ_ERRORS:
+            return 500, failure_payload(
+                service_errors.TRACE_READ_FAILED,
+                "runtime run trace could not be read",
+            )
+        if refreshed_trace is None or not is_runtime_trace(refreshed_trace):
+            return 404, failure_payload(
+                service_errors.NOT_FOUND,
+                "runtime run trace not found",
+            )
+        trace = refreshed_trace
+        owner_auth_subject = str(trace.get("auth_subject", "")) or auth_subject
+        if auth_subject and not request_auth_is_admin and owner_auth_subject != auth_subject:
+            return 404, failure_payload(
+                service_errors.NOT_FOUND,
+                "runtime run trace not found",
+            )
+    trace_status = str(trace.get("status", ""))
+    if trace_status in _TERMINAL_RUNTIME_STATUSES:
+        return 409, failure_payload(
+            service_errors.INVALID_REQUEST_BODY,
+            "runtime run is already terminal",
+        )
+    if trace_status == "resuming":
+        return 409, failure_payload(
+            service_errors.INVALID_REQUEST_BODY,
+            "runtime run approval is being resumed",
+        )
+
+    cancelled_at = _utc_timestamp()
+    try:
+        trace = persist_cancelled_runtime_trace(
+            run_id=run_id,
+            trace_dir=service_config.trace_dir,
+            active_run=ActiveRunSnapshot(
+                run_id=run_id,
+                owner_auth_subject=owner_auth_subject,
+                state="cancelled",
+                started_at=str(trace.get("started_at", "")) or cancelled_at,
+                cancel_reason=reason,
+                cancelled_at=cancelled_at,
+            ),
+            cancelled_by_auth_subject=auth_subject,
+        )
+    except (OSError, ValueError) as exc:
+        return 500, failure_payload(
+            service_errors.TRACE_PERSISTENCE_FAILED,
+            f"could not persist trace: {exc}",
+        )
+    persisted_status = str(trace.get("status", ""))
+    if persisted_status == "resuming":
+        return 409, failure_payload(
+            service_errors.INVALID_REQUEST_BODY,
+            "runtime run approval is being resumed",
+        )
+    if persisted_status != "cancelled":
+        return 409, failure_payload(
+            service_errors.INVALID_REQUEST_BODY,
+            "runtime run is already terminal",
+        )
+    return 200, json_ready(
+        runtime_status_summary(trace, service_config.trace_dir, run_id)
+    )
+
+
+def _utc_timestamp() -> str:
+    return datetime.now(timezone.utc).isoformat()

package/src/kagent/service/runtime_lifecycle.py

@@ -0,0 +1,229 @@
+from __future__ import annotations
+
+import time
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict
+
+from kagent.runtime import RUNTIME_TRACE_TYPE
+from kagent.service.active_runs import ActiveRunSnapshot
+from kagent.service.trace_store import (
+    load_trace_by_run_id,
+    persist_trace,
+    runtime_trace_lock,
+    trace_path_for_run_id,
+)
+
+_TERMINAL_RUNTIME_STATUSES = {"cancelled", "done", "failed", "resumed"}
+_CANCELLATION_PROTECTED_STATUSES = _TERMINAL_RUNTIME_STATUSES | {"resuming"}
+TracePersistFunction = Callable[[Dict[str, Any], str], str]
+
+
+def running_runtime_trace(
+    *,
+    run_id: str,
+    goal: str,
+    max_iterations: int,
+    auth_subject: str = "",
+    resumed_from_run_id: str = "",
+    runtime_instance_id: str = "",
+) -> Dict[str, Any]:
+    started_at = _utc_timestamp()
+    trace: Dict[str, Any] = {
+        "trace_type": RUNTIME_TRACE_TYPE,
+        "run_id": run_id,
+        "status": "running",
+        "goal": goal,
+        "started_at": started_at,
+        "max_iterations": str(max_iterations),
+        "iteration_count": "0",
+        "iteration_budget_remaining": str(max_iterations),
+        "events": [],
+        "observations": [],
+        "plans": [],
+        "plan": {"actions": []},
+    }
+    if auth_subject:
+        trace["auth_subject"] = auth_subject
+    if resumed_from_run_id:
+        trace["resumed_from_run_id"] = resumed_from_run_id
+    if runtime_instance_id:
+        trace["runtime_instance_id"] = runtime_instance_id
+    return trace
+
+
+def persist_cancelled_runtime_trace(
+    *,
+    run_id: str,
+    trace_dir: str,
+    active_run: ActiveRunSnapshot,
+    cancelled_by_auth_subject: str = "",
+    error_code: str = "run_cancelled",
+    error: str = "runtime run cancelled",
+) -> Dict[str, Any]:
+    with runtime_trace_lock(run_id, trace_dir):
+        trace = load_trace_by_run_id(run_id, trace_dir) or {
+            "trace_type": RUNTIME_TRACE_TYPE,
+            "run_id": run_id,
+            "status": "running",
+            "started_at": active_run.started_at,
+            "events": [],
+        }
+        current_status = str(trace.get("status", ""))
+        timeout_upgrade = (
+            active_run.state == "timed_out" and current_status == "cancelled"
+        )
+        if current_status in _CANCELLATION_PROTECTED_STATUSES and not timeout_upgrade:
+            return _with_trace_path(trace, run_id, trace_dir)
+        cancelled_at = active_run.cancelled_at or _utc_timestamp()
+        trace["status"] = "cancelled"
+        trace["completed_at"] = cancelled_at
+        trace["cancelled_at"] = cancelled_at
+        trace["error_code"] = error_code
+        trace["error"] = error
+        if cancelled_by_auth_subject:
+            trace["cancelled_by_auth_subject"] = cancelled_by_auth_subject
+        if active_run.cancel_reason:
+            trace["cancel_reason"] = active_run.cancel_reason
+        trace.pop("pending_approval", None)
+        _append_cancel_event(trace, cancelled_at, active_run.cancel_reason)
+        _refresh_duration_seconds(trace)
+        trace["trace_path"] = persist_trace(trace, trace_dir)
+        return trace
+
+
+def persist_failed_runtime_trace(
+    *,
+    run_id: str,
+    trace_dir: str,
+    error_code: str,
+    error: str,
+) -> Dict[str, Any]:
+    with runtime_trace_lock(run_id, trace_dir):
+        trace = load_trace_by_run_id(run_id, trace_dir) or {
+            "trace_type": RUNTIME_TRACE_TYPE,
+            "run_id": run_id,
+            "status": "running",
+            "started_at": _utc_timestamp(),
+            "events": [],
+        }
+        if str(trace.get("status", "")) in _TERMINAL_RUNTIME_STATUSES:
+            return _with_trace_path(trace, run_id, trace_dir)
+        completed_at = _utc_timestamp()
+        trace["status"] = "failed"
+        trace["completed_at"] = completed_at
+        trace["error_code"] = error_code
+        trace["error"] = error
+        trace.pop("pending_approval", None)
+        _append_failure_event(trace, completed_at, error_code, error)
+        _refresh_duration_seconds(trace)
+        trace["trace_path"] = persist_trace(trace, trace_dir)
+        return trace
+
+
+def persist_runtime_worker_result(
+    *,
+    run_id: str,
+    trace_dir: str,
+    result: Dict[str, Any],
+    persist_trace_fn: TracePersistFunction,
+) -> Dict[str, Any]:
+    """Persist a worker result unless another replica already committed a terminal state."""
+
+    with runtime_trace_lock(run_id, trace_dir):
+        try:
+            current = load_trace_by_run_id(run_id, trace_dir)
+        except ValueError:
+            current = None
+        if current is not None and str(current.get("status", "")) in (
+            _TERMINAL_RUNTIME_STATUSES
+        ):
+            return _with_trace_path(current, run_id, trace_dir)
+        result["trace_path"] = persist_trace_fn(result, trace_dir)
+        return result
+
+
+def persisted_runtime_cancellation_probe(
+    *,
+    run_id: str,
+    trace_dir: str,
+) -> Dict[str, str] | None:
+    trace = load_trace_by_run_id(run_id, trace_dir)
+    if trace is None or str(trace.get("status", "")) != "cancelled":
+        return None
+    return {
+        "reason": str(trace.get("cancel_reason", "")),
+        "cancelled_at": str(trace.get("cancelled_at", "")),
+    }
+
+
+def _with_trace_path(
+    trace: Dict[str, Any],
+    run_id: str,
+    trace_dir: str,
+) -> Dict[str, Any]:
+    trace["trace_path"] = str(trace_path_for_run_id(run_id, trace_dir))
+    return trace
+
+
+def _append_cancel_event(trace: Dict[str, Any], cancelled_at: str, reason: str) -> None:
+    events = trace.get("events")
+    if not isinstance(events, list):
+        events = []
+        trace["events"] = events
+    if any(
+        isinstance(event, dict)
+        and event.get("node") == "control"
+        and event.get("status") == "cancelled"
+        for event in events
+    ):
+        return
+    event: Dict[str, Any] = {
+        "node": "control",
+        "status": "cancelled",
+        "started_at": cancelled_at,
+        "completed_at": cancelled_at,
+        "duration_seconds": "0.0000",
+    }
+    if reason:
+        event["reason"] = reason
+    events.append(event)
+
+
+def _append_failure_event(
+    trace: Dict[str, Any],
+    completed_at: str,
+    error_code: str,
+    error: str,
+) -> None:
+    events = trace.get("events")
+    if not isinstance(events, list):
+        events = []
+        trace["events"] = events
+    events.append(
+        {
+            "node": "runtime",
+            "status": "failed",
+            "started_at": completed_at,
+            "completed_at": completed_at,
+            "duration_seconds": "0.0000",
+            "error_code": error_code,
+            "error": error,
+        }
+    )
+
+
+def _refresh_duration_seconds(trace: Dict[str, Any]) -> None:
+    started_at = trace.get("started_at")
+    if not isinstance(started_at, str) or not started_at.strip():
+        return
+    try:
+        started = datetime.fromisoformat(started_at)
+    except ValueError:
+        return
+    if started.tzinfo is None:
+        started = started.replace(tzinfo=timezone.utc)
+    trace["duration_seconds"] = f"{max(0.0, time.time() - started.timestamp()):.4f}"
+
+
+def _utc_timestamp() -> str:
+    return datetime.now(timezone.utc).isoformat()

package/src/kagent/service/runtime_metadata.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from kagent.runtime.metadata import (
+    MAX_RUNTIME_METADATA_ENTRIES,
+    MAX_RUNTIME_METADATA_KEY_CHARS,
+    MAX_RUNTIME_METADATA_VALUE_CHARS,
+    MAX_RUNTIME_TAG_CHARS,
+    MAX_RUNTIME_TAGS,
+    validate_runtime_metadata,
+    validate_runtime_tags,
+)
+
+__all__ = [
+    "MAX_RUNTIME_METADATA_ENTRIES",
+    "MAX_RUNTIME_METADATA_KEY_CHARS",
+    "MAX_RUNTIME_METADATA_VALUE_CHARS",
+    "MAX_RUNTIME_TAG_CHARS",
+    "MAX_RUNTIME_TAGS",
+    "validate_runtime_metadata",
+    "validate_runtime_tags",
+]

package/src/kagent/service/runtime_policy.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import json
+from hashlib import sha256
+from typing import Any, Dict, Tuple
+
+from kagent.runtime import RUNTIME_TRACE_TYPE
+from kagent.runtime.policy import RuntimePolicy
+from kagent.runtime.tools import default_runtime_tools
+from kagent.service.runtime import ServiceConfig
+from kagent.utils.json_output import json_ready
+
+
+def execute_runtime_policy_request(
+    service_config: ServiceConfig,
+    *,
+    request_auth_subject: str = "",
+    request_auth_is_admin: bool = False,
+) -> Tuple[int, Dict[str, Any]]:
+    default_allowed_tools = _sorted_tuple(RuntimePolicy().allowed_tools)
+    global_allowed_tools = _sorted_tuple(service_config.runtime_allowed_tools)
+    subject_allowed_tools = _subject_allowed_tools(
+        service_config,
+        request_auth_subject=request_auth_subject,
+        request_auth_is_admin=request_auth_is_admin,
+    )
+    effective_allowed_tools, effective_policy_source = _effective_policy(
+        service_config,
+        request_auth_subject=request_auth_subject,
+        default_allowed_tools=default_allowed_tools,
+        global_allowed_tools=global_allowed_tools,
+    )
+    effective_tool_policy = _effective_tool_policy(effective_allowed_tools)
+    return 200, json_ready(
+        {
+            "trace_type": RUNTIME_TRACE_TYPE,
+            "auth_subject": request_auth_subject,
+            "is_admin": str(request_auth_is_admin).lower(),
+            "default_allowed_tools": list(default_allowed_tools),
+            "global_allowed_tools": list(global_allowed_tools),
+            "subject_policy_count": str(
+                len(service_config.runtime_allowed_tools_by_subject)
+            ),
+            "subject_allowed_tools": subject_allowed_tools,
+            "effective_allowed_tools": list(effective_allowed_tools),
+            "effective_policy_source": effective_policy_source,
+            "effective_tool_policy": effective_tool_policy,
+            "effective_tool_policy_sha256": _policy_sha256(
+                effective_tool_policy
+            ),
+        }
+    )
+
+
+def _subject_allowed_tools(
+    service_config: ServiceConfig,
+    *,
+    request_auth_subject: str,
+    request_auth_is_admin: bool,
+) -> Dict[str, list[str]]:
+    subjects = service_config.runtime_allowed_tools_by_subject
+    if request_auth_is_admin:
+        return {
+            subject: list(_sorted_tuple(tools))
+            for subject, tools in sorted(subjects.items())
+        }
+    if request_auth_subject in subjects:
+        return {
+            request_auth_subject: list(
+                _sorted_tuple(subjects[request_auth_subject])
+            )
+        }
+    return {}
+
+
+def _effective_policy(
+    service_config: ServiceConfig,
+    *,
+    request_auth_subject: str,
+    default_allowed_tools: tuple[str, ...],
+    global_allowed_tools: tuple[str, ...],
+) -> tuple[tuple[str, ...], str]:
+    subject_allowed_tools = service_config.runtime_allowed_tools_by_subject.get(
+        request_auth_subject,
+    )
+    if subject_allowed_tools is not None:
+        return _sorted_tuple(subject_allowed_tools), "subject"
+    if global_allowed_tools:
+        return global_allowed_tools, "global"
+    return default_allowed_tools, "default"
+
+
+def _sorted_tuple(values: Any) -> tuple[str, ...]:
+    if not values:
+        return ()
+    return tuple(sorted(str(value) for value in values if str(value).strip()))
+
+
+def _effective_tool_policy(
+    effective_allowed_tools: tuple[str, ...],
+) -> list[dict[str, str]]:
+    allowed_tools = set(effective_allowed_tools)
+    return [
+        {
+            "name": name,
+            "allowed": str(name in allowed_tools).lower(),
+            "approval_required": str(name not in allowed_tools).lower(),
+        }
+        for name in sorted(default_runtime_tools())
+    ]
+
+
+def _policy_sha256(policy: list[dict[str, str]]) -> str:
+    payload = json.dumps(policy, sort_keys=True, separators=(",", ":"))
+    return sha256(payload.encode("utf-8")).hexdigest()