@openlucaskaka/kagent 0.1.7

package/src/kagent/runtime/redaction.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+import re
+import urllib.parse
+from typing import Any
+
+REDACTED_VALUE = "[REDACTED]"
+
+_URL_PATTERN = re.compile(r"https?://[^\s\"'<>]+")
+_URL_SECRET_KEY_PARTS = (
+    "api_key",
+    "apikey",
+    "authorization",
+    "bearer",
+    "password",
+    "secret",
+    "token",
+)
+_API_KEY_PATTERN = re.compile(r"\bsk-[A-Za-z0-9:_-]{6,}\b")
+_BEARER_TOKEN_PATTERN = re.compile(
+    r"(?i)\b(bearer[\s-]+)([A-Za-z0-9._:/+=-]{6,})"
+)
+_GITHUB_TOKEN_PATTERN = re.compile(
+    r"\b(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})\b"
+)
+_KNOWN_SECRET_ASSIGNMENT_PATTERN = re.compile(
+    r"(?i)(\b(?:api[_-]?key|access[_-]?token|auth[_-]?token|client[_-]?secret|"
+    r"github[_-]?token|password|secret[_-]?key)[\"']?\s*[:=]\s*[\"']?)"
+    r"([^\s\"',;}{&#\[\]]{4,})([\"']?)"
+)
+_ENV_SECRET_ASSIGNMENT_PATTERN = re.compile(
+    r"(\b[A-Z][A-Z0-9_]*(?:API_KEY|ACCESS_TOKEN|AUTH_TOKEN|CLIENT_SECRET|"
+    r"SECRET_ACCESS_KEY|SECRET_KEY|PASSWORD|PRIVATE_KEY|TOKEN)[\"']?"
+    r"\s*[:=]\s*[\"']?)([^\s\"',;}{&#\[\]]{4,})([\"']?)"
+)
+_PRIVATE_KEY_PATTERN = re.compile(
+    r"-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----.*?"
+    r"-----END [A-Z0-9 ]*PRIVATE KEY-----",
+    re.DOTALL,
+)
+_SECRET_VALUE_PATTERNS = (
+    _API_KEY_PATTERN,
+    _BEARER_TOKEN_PATTERN,
+    _GITHUB_TOKEN_PATTERN,
+)
+
+
+def redact_runtime_payload(value: Any) -> Any:
+    if isinstance(value, str):
+        return redact_runtime_text(value)
+    if isinstance(value, dict):
+        return {key: redact_runtime_payload(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [redact_runtime_payload(item) for item in value]
+    return value
+
+
+def redact_runtime_text(value: str) -> str:
+    redacted = _URL_PATTERN.sub(lambda match: _redact_url(match.group(0)), value)
+    redacted = _PRIVATE_KEY_PATTERN.sub(REDACTED_VALUE, redacted)
+    redacted = _KNOWN_SECRET_ASSIGNMENT_PATTERN.sub(_redact_assignment, redacted)
+    redacted = _ENV_SECRET_ASSIGNMENT_PATTERN.sub(_redact_assignment, redacted)
+    redacted = _API_KEY_PATTERN.sub(REDACTED_VALUE, redacted)
+    redacted = _GITHUB_TOKEN_PATTERN.sub(REDACTED_VALUE, redacted)
+    return _BEARER_TOKEN_PATTERN.sub(
+        lambda match: match.group(1) + REDACTED_VALUE,
+        redacted,
+    )
+
+
+def _redact_assignment(match: re.Match[str]) -> str:
+    return f"{match.group(1)}{REDACTED_VALUE}{match.group(3)}"
+
+
+def _redact_url(value: str) -> str:
+    parsed = urllib.parse.urlsplit(value)
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        return value
+    return urllib.parse.urlunsplit(
+        (
+            parsed.scheme,
+            _redact_url_netloc(parsed.netloc),
+            parsed.path,
+            _redact_url_component(parsed.query),
+            _redact_url_component(parsed.fragment),
+        )
+    )
+
+
+def _redact_url_netloc(netloc: str) -> str:
+    if "@" not in netloc:
+        return netloc
+    return f"{REDACTED_VALUE}@{netloc.rsplit('@', 1)[1]}"
+
+
+def _redact_url_component(value: str) -> str:
+    if not value:
+        return value
+    if "=" not in value and _contains_secret_like_value(urllib.parse.unquote_plus(value)):
+        return REDACTED_VALUE
+    parts = []
+    for item in value.split("&"):
+        if "=" not in item:
+            parts.append(_redact_bare_url_component_item(item))
+            continue
+        key, item_value = item.split("=", 1)
+        decoded_key = urllib.parse.unquote_plus(key).lower()
+        decoded_value = urllib.parse.unquote_plus(item_value)
+        if _is_secret_like_key(decoded_key) or _contains_secret_like_value(decoded_value):
+            parts.append(f"{key}={REDACTED_VALUE}")
+        else:
+            parts.append(item)
+    return "&".join(parts)
+
+
+def _redact_bare_url_component_item(value: str) -> str:
+    decoded_value = urllib.parse.unquote_plus(value)
+    if _is_secret_like_key(decoded_value.lower()) or _contains_secret_like_value(
+        decoded_value
+    ):
+        return REDACTED_VALUE
+    return value
+
+
+def _is_secret_like_key(value: str) -> bool:
+    return any(part in value for part in _URL_SECRET_KEY_PARTS)
+
+
+def _contains_secret_like_value(value: str) -> bool:
+    return any(pattern.search(value) for pattern in _SECRET_VALUE_PATTERNS)

package/src/kagent/runtime/sandbox.py

@@ -0,0 +1,331 @@
+from __future__ import annotations
+
+import platform
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, List, Sequence, Union
+
+SandboxArgv = Union[str, List[str]]
+
+
+@dataclass(frozen=True)
+class ShellSandboxExecution:
+    argv: SandboxArgv
+    shell: bool
+    env: Dict[str, str]
+    metadata: Dict[str, str]
+    profile: str = ""
+
+
+@dataclass(frozen=True)
+class ShellSandboxResult:
+    completed: subprocess.CompletedProcess
+    metadata: Dict[str, str]
+
+
+def prepare_shell_sandbox(
+    command: str,
+    *,
+    workspace_root: Path,
+    cwd: Path,
+    env: Dict[str, str],
+) -> ShellSandboxExecution:
+    system = platform.system().lower()
+    if system == "darwin":
+        return _prepare_macos_seatbelt(command, workspace_root=workspace_root, env=env)
+    if system == "linux":
+        return _prepare_linux_bwrap(command, workspace_root=workspace_root, cwd=cwd, env=env)
+    if system == "windows":
+        return _soft_execution(command, env=env, backend="windows-soft")
+    return _soft_execution(command, env=env, backend="soft")
+
+
+def run_shell_sandboxed(
+    command: str,
+    *,
+    workspace_root: Path,
+    cwd: Path,
+    env: Dict[str, str],
+    timeout_seconds: float,
+) -> ShellSandboxResult:
+    execution = prepare_shell_sandbox(
+        command,
+        workspace_root=workspace_root,
+        cwd=cwd,
+        env=env,
+    )
+    try:
+        completed = _run_prepared_execution(execution, cwd=cwd, timeout_seconds=timeout_seconds)
+        if _native_sandbox_startup_failed(execution, completed):
+            fallback = _soft_execution(
+                command,
+                env=env,
+                backend="soft",
+                fallback_reason="native sandbox startup failed",
+            )
+            completed = _run_prepared_execution(
+                fallback,
+                cwd=cwd,
+                timeout_seconds=timeout_seconds,
+            )
+            return ShellSandboxResult(completed=completed, metadata=fallback.metadata)
+        return ShellSandboxResult(completed=completed, metadata=execution.metadata)
+    except (FileNotFoundError, PermissionError, OSError):
+        fallback = _soft_execution(
+            command,
+            env=env,
+            backend="soft",
+            fallback_reason="native sandbox exec failed",
+        )
+        completed = _run_prepared_execution(fallback, cwd=cwd, timeout_seconds=timeout_seconds)
+        return ShellSandboxResult(completed=completed, metadata=fallback.metadata)
+
+
+def _run_prepared_execution(
+    execution: ShellSandboxExecution,
+    *,
+    cwd: Path,
+    timeout_seconds: float,
+) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        execution.argv,
+        shell=execution.shell,
+        cwd=str(cwd),
+        env=execution.env,
+        stdin=subprocess.DEVNULL,
+        capture_output=True,
+        text=False,
+        timeout=timeout_seconds,
+        start_new_session=True,
+    )
+
+
+def _native_sandbox_startup_failed(
+    execution: ShellSandboxExecution,
+    completed: subprocess.CompletedProcess,
+) -> bool:
+    if execution.metadata.get("enforced") != "true" or completed.returncode == 0:
+        return False
+    stderr = (completed.stderr or b"").decode("utf-8", errors="replace").lower()
+    backend = execution.metadata.get("backend", "")
+    if backend == "linux-bwrap":
+        startup_markers = (
+            "creating new namespace failed",
+            "bubblewrap:",
+            "bwrap:",
+            "failed to make",
+        )
+        return any(marker in stderr for marker in startup_markers)
+    if backend == "macos-seatbelt":
+        return "sandbox-exec: execvp" in stderr
+    return False
+
+
+def _prepare_macos_seatbelt(
+    command: str,
+    *,
+    workspace_root: Path,
+    env: Dict[str, str],
+) -> ShellSandboxExecution:
+    sandbox_exec = shutil.which("sandbox-exec")
+    if not sandbox_exec:
+        return _soft_execution(
+            command,
+            env=env,
+            backend="soft",
+            fallback_reason="native sandbox unavailable",
+        )
+    profile = _macos_seatbelt_profile(workspace_root)
+    return ShellSandboxExecution(
+        argv=[
+            sandbox_exec,
+            "-p",
+            profile,
+            "/bin/bash",
+            "--noprofile",
+            "--norc",
+            "-c",
+            command,
+        ],
+        shell=False,
+        env=env,
+        metadata=_sandbox_metadata(backend="macos-seatbelt", enforced=True),
+        profile=profile,
+    )
+
+
+def _prepare_linux_bwrap(
+    command: str,
+    *,
+    workspace_root: Path,
+    cwd: Path,
+    env: Dict[str, str],
+) -> ShellSandboxExecution:
+    bwrap = shutil.which("bwrap")
+    if not bwrap:
+        return _soft_execution(
+            command,
+            env=env,
+            backend="soft",
+            fallback_reason="native sandbox unavailable",
+        )
+    argv: List[str] = [
+        bwrap,
+        "--die-with-parent",
+        "--new-session",
+        "--unshare-all",
+        "--unshare-net",
+        "--proc",
+        "/proc",
+        "--dev",
+        "/dev",
+        "--tmpfs",
+        "/tmp",
+    ]
+    for source in _linux_readonly_binds():
+        argv.extend(["--ro-bind", source, source])
+    argv.extend(["--bind", str(workspace_root), str(workspace_root)])
+    argv.extend(["--chdir", str(cwd)])
+    argv.extend(["/bin/sh", "-lc", command])
+    return ShellSandboxExecution(
+        argv=argv,
+        shell=False,
+        env=env,
+        metadata=_sandbox_metadata(backend="linux-bwrap", enforced=True),
+    )
+
+
+def _linux_readonly_binds() -> Sequence[str]:
+    candidates = (
+        "/bin",
+        "/usr",
+        "/lib",
+        "/lib64",
+        "/etc/alternatives",
+        "/etc/ssl",
+        "/etc/ca-certificates",
+    )
+    return tuple(path for path in candidates if Path(path).exists())
+
+
+def _soft_execution(
+    command: str,
+    *,
+    env: Dict[str, str],
+    backend: str,
+    fallback_reason: str = "",
+) -> ShellSandboxExecution:
+    return ShellSandboxExecution(
+        argv=command,
+        shell=True,
+        env=env,
+        metadata=_sandbox_metadata(
+            backend=backend,
+            enforced=False,
+            fallback_reason=fallback_reason,
+        ),
+    )
+
+
+def _sandbox_metadata(
+    *,
+    backend: str,
+    enforced: bool,
+    fallback_reason: str = "",
+) -> Dict[str, str]:
+    metadata = {
+        "enabled": "true",
+        "backend": backend,
+        "enforced": "true" if enforced else "false",
+        "filesystem": "workspace",
+        "network": "disabled",
+        "env_policy": "minimal",
+    }
+    if fallback_reason:
+        metadata["fallback_reason"] = fallback_reason
+    return metadata
+
+
+def _macos_seatbelt_profile(workspace_root: Path) -> str:
+    workspace_read_rules = " ".join(
+        f"(subpath {_seatbelt_string(str(path))})"
+        for path in _macos_path_aliases(workspace_root)
+    )
+    read_exception_filters = _macos_read_exception_filters(workspace_root)
+    runtime_read_rules = " ".join(
+        f"(subpath {_seatbelt_string(str(path))})"
+        for runtime_path in _macos_runtime_read_paths()
+        for path in _macos_path_aliases(runtime_path)
+    )
+    workspace_write_rules = " ".join(
+        f"(subpath {_seatbelt_string(str(path))})"
+        for path in _macos_path_aliases(workspace_root)
+    )
+    return "\n".join(
+        [
+            "(version 1)",
+            "(allow default)",
+            "(deny network*)",
+            "(deny file-read*",
+            "  (require-all",
+            '    (subpath "/Users")',
+            "    (require-not",
+            "      (require-any",
+            f"        {read_exception_filters}))))",
+            f"(allow file-read* {workspace_read_rules})",
+            f"(allow file-read* {runtime_read_rules})" if runtime_read_rules else "",
+            "(deny file-write*)",
+            f"(allow file-write* {workspace_write_rules})",
+        ]
+    )
+
+
+def _seatbelt_string(value: str) -> str:
+    escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+    return f'"{escaped}"'
+
+
+def _macos_runtime_read_paths() -> Sequence[Path]:
+    candidates = {
+        Path(sys.executable).absolute().parent,
+        Path(sys.executable).resolve().parent,
+        Path(sys.prefix).resolve(),
+    }
+    return tuple(path for path in candidates if str(path).startswith("/Users/"))
+
+
+def _macos_read_exception_filters(workspace_root: Path) -> str:
+    subpaths = set(_macos_path_aliases(workspace_root))
+    for runtime_path in _macos_runtime_read_paths():
+        subpaths.update(_macos_path_aliases(runtime_path))
+    literals = set(subpaths)
+    for path in tuple(subpaths):
+        literals.update(_macos_user_ancestor_literals(path))
+    filters = [
+        f"(subpath {_seatbelt_string(str(path))})"
+        for path in sorted(subpaths, key=str)
+    ]
+    filters.extend(
+        f"(literal {_seatbelt_string(str(path))})"
+        for path in sorted(literals, key=str)
+    )
+    return " ".join(filters)
+
+
+def _macos_user_ancestor_literals(path: Path) -> Sequence[Path]:
+    candidates = [path]
+    candidates.extend(path.parents)
+    return tuple(candidate for candidate in candidates if str(candidate).startswith("/Users"))
+
+
+def _macos_path_aliases(path: Path) -> Sequence[Path]:
+    path_text = str(path)
+    aliases = {path}
+    if path_text.startswith(("/var/", "/tmp/", "/etc/")):
+        aliases.add(Path(f"/private{path_text}"))
+    if path_text.startswith("/private/"):
+        aliases.add(Path(path_text.removeprefix("/private")))
+    return tuple(aliases)

package/src/kagent/runtime/skills.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any, Dict
+
+_SAFE_SKILL_NAME = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,79}$")
+
+
+class RuntimeSkillRegistry:
+    def __init__(self, skills_dir: str | Path) -> None:
+        self.skills_dir = Path(skills_dir)
+
+    def list_skills(self) -> list[Dict[str, Any]]:
+        if not self.skills_dir.exists():
+            return []
+        skills = []
+        for path in sorted(self.skills_dir.glob("*.json")):
+            if path.is_symlink() or not path.is_file():
+                continue
+            skill = self._read_skill_file(path)
+            skills.append(
+                {
+                    "name": skill["name"],
+                    "description": skill["description"],
+                    "tags": skill.get("tags", []),
+                }
+            )
+        return skills
+
+    def get_skill(self, name: str) -> Dict[str, Any]:
+        normalized_name = self._validate_skill_name(name)
+        path = self.skills_dir / f"{normalized_name}.json"
+        if path.is_symlink():
+            raise ValueError("skill file must not be a symlink")
+        if not path.exists():
+            raise ValueError(f"skill does not exist: {normalized_name}")
+        return self._read_skill_file(path)
+
+    def _read_skill_file(self, path: Path) -> Dict[str, Any]:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+        if not isinstance(payload, dict):
+            raise ValueError("skill payload must be an object")
+        name = self._validate_skill_name(str(payload.get("name", "")))
+        description = str(payload.get("description", "")).strip()
+        instructions = str(payload.get("instructions", "")).strip()
+        if not description:
+            raise ValueError(f"skill description is required: {name}")
+        if not instructions:
+            raise ValueError(f"skill instructions are required: {name}")
+        tags = payload.get("tags", [])
+        if not isinstance(tags, list):
+            raise ValueError(f"skill tags must be an array: {name}")
+        return {
+            "name": name,
+            "description": description,
+            "instructions": instructions,
+            "tags": [str(tag) for tag in tags],
+        }
+
+    def _validate_skill_name(self, name: str) -> str:
+        normalized = str(name).strip()
+        if not _SAFE_SKILL_NAME.match(normalized):
+            raise ValueError("skill name must be a safe identifier")
+        return normalized

package/src/kagent/runtime/steering.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from threading import Lock
+from typing import Callable
+
+
+class RuntimeSteeringBuffer:
+    """Thread-safe latest-wins instruction slot for an active runtime run."""
+
+    def __init__(self) -> None:
+        self._lock = Lock()
+        self._instruction = ""
+        self._revision = 0
+        self._closed = False
+
+    def submit(
+        self,
+        instruction: str,
+        *,
+        accepted: Callable[[dict[str, str]], None] | None = None,
+    ) -> dict[str, str]:
+        normalized = instruction.strip()
+        if not normalized:
+            raise ValueError("steering instruction is required")
+        with self._lock:
+            if self._closed:
+                raise RuntimeError("active run is no longer accepting steering")
+            replaced = bool(self._instruction)
+            self._instruction = normalized
+            self._revision += 1
+            snapshot = {
+                "revision": str(self._revision),
+                "replaced": str(replaced).lower(),
+            }
+            if accepted is not None:
+                accepted(snapshot)
+            return snapshot
+
+    def consume(self) -> tuple[str, str]:
+        with self._lock:
+            instruction = self._instruction
+            if not instruction:
+                return "", str(self._revision)
+            self._instruction = ""
+            return instruction, str(self._revision)
+
+    def pending(self) -> bool:
+        with self._lock:
+            return bool(self._instruction)
+
+    def close(self) -> tuple[str, str]:
+        with self._lock:
+            self._closed = True
+            instruction = self._instruction
+            self._instruction = ""
+            return instruction, str(self._revision)