@openlucaskaka/kagent 0.1.7

package/src/kagent/runtime/file_transaction.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+import fcntl
+import os
+import stat
+import tempfile
+from contextlib import contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterator
+
+
+@dataclass(frozen=True)
+class TextFileState:
+    content: str | None
+    mode: int
+
+
+@contextmanager
+def workspace_transaction(workspace_root: Path) -> Iterator[None]:
+    flags = os.O_RDONLY
+    if hasattr(os, "O_DIRECTORY"):
+        flags |= os.O_DIRECTORY
+    if hasattr(os, "O_NOFOLLOW"):
+        flags |= os.O_NOFOLLOW
+    descriptor = os.open(workspace_root, flags)
+    try:
+        fcntl.flock(descriptor, fcntl.LOCK_EX)
+        yield
+    finally:
+        try:
+            fcntl.flock(descriptor, fcntl.LOCK_UN)
+        finally:
+            os.close(descriptor)
+
+
+def commit_text_changes(
+    workspace_root: Path,
+    staged_contents: dict[Path, str | None],
+    *,
+    original_states: dict[Path, TextFileState] | None = None,
+    target_modes: dict[Path, int] | None = None,
+) -> None:
+    snapshots = original_states or capture_text_states(staged_contents)
+    resolved_target_modes = target_modes or {}
+    created_directories: list[Path] = []
+    try:
+        for target, content in staged_contents.items():
+            _reject_symlink_parts(workspace_root, target)
+            if content is None:
+                if target.exists():
+                    target.unlink()
+                    _fsync_directory(target.parent)
+                continue
+            _ensure_parent(
+                workspace_root,
+                target.parent,
+                created_directories=created_directories,
+            )
+            _atomic_write_text(target, content, mode=resolved_target_modes.get(target))
+    except Exception as commit_error:
+        try:
+            _rollback(
+                workspace_root,
+                snapshots,
+                created_directories=created_directories,
+            )
+        except Exception as rollback_error:
+            raise RuntimeError(
+                f"patch commit failed: {commit_error}; rollback failed: {rollback_error}"
+            ) from commit_error
+        raise
+
+
+def capture_text_states(paths) -> dict[Path, TextFileState]:
+    return {target: _snapshot(target) for target in paths}
+
+
+def validate_workspace_targets(workspace_root: Path, paths) -> None:
+    for target in paths:
+        target.relative_to(workspace_root)
+        _reject_symlink_parts(workspace_root, target)
+
+
+def _snapshot(target: Path) -> TextFileState:
+    if not target.exists():
+        return TextFileState(content=None, mode=0o600)
+    if not target.is_file():
+        raise ValueError("path is not a regular file")
+    return TextFileState(
+        content=target.read_text(encoding="utf-8"),
+        mode=stat.S_IMODE(target.stat().st_mode),
+    )
+
+
+def _rollback(
+    workspace_root: Path,
+    snapshots: dict[Path, TextFileState],
+    *,
+    created_directories: list[Path],
+) -> None:
+    errors = []
+    for target, snapshot in reversed(tuple(snapshots.items())):
+        try:
+            _reject_symlink_parts(workspace_root, target)
+            if snapshot.content is None:
+                if target.exists():
+                    target.unlink()
+                    _fsync_directory(target.parent)
+                continue
+            _ensure_parent(workspace_root, target.parent, created_directories=[])
+            _atomic_write_text(target, snapshot.content, mode=snapshot.mode)
+        except Exception as exc:
+            relative_path = target.relative_to(workspace_root).as_posix()
+            errors.append(f"{relative_path}: {exc}")
+    for directory in reversed(created_directories):
+        try:
+            directory.rmdir()
+            _fsync_directory(directory.parent)
+        except OSError:
+            continue
+    if errors:
+        raise RuntimeError("; ".join(errors))
+
+
+def _reject_symlink_parts(workspace_root: Path, target: Path) -> None:
+    current = workspace_root
+    for part in target.relative_to(workspace_root).parts:
+        current = current / part
+        if current.is_symlink():
+            raise ValueError("path must not be a symlink")
+        if not current.exists():
+            return
+
+
+def _ensure_parent(
+    workspace_root: Path,
+    target_parent: Path,
+    *,
+    created_directories: list[Path],
+) -> None:
+    current = workspace_root
+    for part in target_parent.relative_to(workspace_root).parts:
+        current = current / part
+        if current.is_symlink():
+            raise ValueError("path must not be a symlink")
+        if current.exists():
+            if not current.is_dir():
+                raise ValueError("parent path is not a directory")
+            continue
+        current.mkdir()
+        created_directories.append(current)
+        _fsync_directory(current.parent)
+
+
+def _atomic_write_text(
+    target: Path,
+    content: str,
+    *,
+    mode: int | None = None,
+) -> None:
+    resolved_mode = mode
+    if resolved_mode is None:
+        resolved_mode = stat.S_IMODE(target.stat().st_mode) if target.exists() else 0o600
+    descriptor, temporary_name = tempfile.mkstemp(
+        prefix=f".{target.name}.",
+        suffix=".tmp",
+        dir=target.parent,
+    )
+    temporary_path = Path(temporary_name)
+    try:
+        os.chmod(temporary_path, resolved_mode)
+        with os.fdopen(descriptor, "w", encoding="utf-8", newline="") as handle:
+            descriptor = -1
+            handle.write(content)
+            handle.flush()
+            os.fsync(handle.fileno())
+        temporary_path.replace(target)
+        _fsync_directory(target.parent)
+    except Exception:
+        if descriptor != -1:
+            os.close(descriptor)
+        temporary_path.unlink(missing_ok=True)
+        raise
+
+
+def _fsync_directory(directory: Path) -> None:
+    flags = os.O_RDONLY
+    if hasattr(os, "O_DIRECTORY"):
+        flags |= os.O_DIRECTORY
+    descriptor = os.open(directory, flags)
+    try:
+        os.fsync(descriptor)
+    finally:
+        os.close(descriptor)

package/src/kagent/runtime/hooks.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Iterable, Protocol
+
+
+@dataclass(frozen=True)
+class RuntimeHookDecision:
+    status: str
+    reason: str = ""
+
+    @classmethod
+    def allow(cls) -> "RuntimeHookDecision":
+        return cls(status="allowed")
+
+    @classmethod
+    def deny(cls, reason: str) -> "RuntimeHookDecision":
+        return cls(status="denied", reason=reason or "runtime hook denied execution")
+
+
+class RuntimeHook(Protocol):
+    def on_run_start(self, context: Dict[str, Any]) -> None:
+        ...
+
+    def before_tool(self, context: Dict[str, Any]) -> RuntimeHookDecision:
+        ...
+
+    def after_tool(self, context: Dict[str, Any]) -> None:
+        ...
+
+    def on_run_end(self, context: Dict[str, Any]) -> None:
+        ...
+
+
+class RuntimeHookChain:
+    def __init__(self, hooks: Iterable[Any] = ()) -> None:
+        self._hooks = tuple(hooks)
+
+    def __bool__(self) -> bool:
+        return bool(self._hooks)
+
+    def on_run_start(self, context: Dict[str, Any]) -> None:
+        for hook in self._hooks:
+            handler = getattr(hook, "on_run_start", None)
+            if callable(handler):
+                handler(dict(context))
+
+    def before_tool(self, context: Dict[str, Any]) -> RuntimeHookDecision:
+        for hook in self._hooks:
+            handler = getattr(hook, "before_tool", None)
+            if not callable(handler):
+                continue
+            decision = handler(dict(context))
+            if decision is None:
+                continue
+            if not isinstance(decision, RuntimeHookDecision):
+                raise ValueError("runtime hook before_tool must return RuntimeHookDecision")
+            if decision.status == "denied":
+                return decision
+            if decision.status != "allowed":
+                raise ValueError("runtime hook decision status must be allowed or denied")
+        return RuntimeHookDecision.allow()
+
+    def after_tool(self, context: Dict[str, Any]) -> None:
+        for hook in self._hooks:
+            handler = getattr(hook, "after_tool", None)
+            if callable(handler):
+                handler(dict(context))
+
+    def on_run_end(self, context: Dict[str, Any]) -> None:
+        for hook in self._hooks:
+            handler = getattr(hook, "on_run_end", None)
+            if callable(handler):
+                handler(dict(context))

package/src/kagent/runtime/metadata.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, Tuple
+
+MAX_RUNTIME_TAGS = 16
+MAX_RUNTIME_TAG_CHARS = 64
+MAX_RUNTIME_METADATA_ENTRIES = 16
+MAX_RUNTIME_METADATA_KEY_CHARS = 64
+MAX_RUNTIME_METADATA_VALUE_CHARS = 256
+
+_SAFE_KEY_CHARS = frozenset(
+    "abcdefghijklmnopqrstuvwxyz"
+    "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+    "0123456789"
+    "._:-"
+)
+_SECRET_KEY_PARTS = (
+    "api_key",
+    "apikey",
+    "authorization",
+    "bearer",
+    "password",
+    "secret",
+    "token",
+)
+_API_KEY_VALUE_PATTERN = re.compile(r"\bsk-[A-Za-z0-9:_-]{8,}\b")
+_BEARER_VALUE_PATTERN = re.compile(
+    r"\b(Authorization:\s*Bearer\s+|Bearer\s+)[A-Za-z0-9._~+/:-]{8,}",
+    re.IGNORECASE,
+)
+_URL_CREDENTIAL_VALUE_PATTERN = re.compile(r"\bhttps?://[^/\s:@]+:[^/\s@]+@")
+
+
+def validate_runtime_metadata(
+    metadata: Any,
+) -> Tuple[Dict[str, str], str]:
+    if metadata is None:
+        return {}, ""
+    if not isinstance(metadata, dict):
+        return {}, "metadata must be a JSON object"
+    if len(metadata) > MAX_RUNTIME_METADATA_ENTRIES:
+        return {}, (
+            f"metadata must contain at most {MAX_RUNTIME_METADATA_ENTRIES} entries"
+        )
+    normalized = {}
+    for raw_key, raw_value in metadata.items():
+        if not isinstance(raw_key, str):
+            return {}, "metadata keys must be strings"
+        key = raw_key.strip()
+        if not key:
+            return {}, "metadata keys must be non-empty strings"
+        if len(key) > MAX_RUNTIME_METADATA_KEY_CHARS:
+            return {}, (
+                f"metadata keys must contain at most "
+                f"{MAX_RUNTIME_METADATA_KEY_CHARS} characters"
+            )
+        if any(character not in _SAFE_KEY_CHARS for character in key):
+            return {}, "metadata keys may only contain letters, numbers, . _ : and -"
+        lowered_key = key.lower()
+        if any(secret_part in lowered_key for secret_part in _SECRET_KEY_PARTS):
+            return {}, "metadata must not contain secret-like keys"
+        if not isinstance(raw_value, str):
+            return {}, "metadata values must be strings"
+        value = raw_value.strip()
+        if len(value) > MAX_RUNTIME_METADATA_VALUE_CHARS:
+            return {}, (
+                f"metadata values must contain at most "
+                f"{MAX_RUNTIME_METADATA_VALUE_CHARS} characters"
+            )
+        if not _safe_runtime_label_value(value):
+            return {}, "metadata values must not contain control characters"
+        if _secret_like_runtime_label_value(value):
+            return {}, "metadata values must not contain secret-like values"
+        normalized[key] = value
+    return {key: normalized[key] for key in sorted(normalized)}, ""
+
+
+def validate_runtime_tags(tags: Any) -> Tuple[list[str], str]:
+    if tags is None:
+        return [], ""
+    if not isinstance(tags, list):
+        return [], "tags must be an array of strings"
+    if len(tags) > MAX_RUNTIME_TAGS:
+        return [], f"tags must contain at most {MAX_RUNTIME_TAGS} entries"
+    normalized = []
+    seen = set()
+    for raw_tag in tags:
+        if not isinstance(raw_tag, str):
+            return [], "tags must be an array of strings"
+        tag = raw_tag.strip()
+        if not tag:
+            return [], "tags must contain non-empty strings"
+        if len(tag) > MAX_RUNTIME_TAG_CHARS:
+            return [], (
+                f"tags must contain strings of at most "
+                f"{MAX_RUNTIME_TAG_CHARS} characters"
+            )
+        if not _safe_runtime_label_value(tag):
+            return [], "tags must not contain control characters"
+        if tag not in seen:
+            seen.add(tag)
+            normalized.append(tag)
+    return sorted(normalized), ""
+
+
+def _safe_runtime_label_value(value: str) -> bool:
+    return all(ord(character) >= 32 for character in value)
+
+
+def _secret_like_runtime_label_value(value: str) -> bool:
+    return bool(
+        _API_KEY_VALUE_PATTERN.search(value)
+        or _BEARER_VALUE_PATTERN.search(value)
+        or _URL_CREDENTIAL_VALUE_PATTERN.search(value)
+    )