agentengine-sdk-python 0.6.2__py3-none-any.whl → 0.6.9__py3-none-any.whl

ksadk/skills/tool_defs.py

@@ -0,0 +1,221 @@
+from __future__ import annotations
+
+import os
+from uuid import uuid4
+
+from ksadk.skills.loader import LocalSkill
+from ksadk.skills.models import SkillRef
+from ksadk.skills.runtime.base import SkillRuntimeBackend, normalize_skill_names
+from ksadk.skills.service_client import SkillServiceClient
+from ksadk.skills.service_env import (
+    parse_skill_space_ids,
+    public_skill_space_ids,
+    resolve_skill_service_url,
+    should_resolve_child_skill_service_url,
+    skill_space_ids as configured_skill_space_ids,
+    user_skill_space_ids,
+)
+
+RUNTIME_AGENT_ENV_NAMES = (
+    "KSADK_SKILL_SERVICE_URL",
+    "KSADK_SKILL_SERVICE_TOKEN",
+    "KSADK_SKILL_SERVICE_ACCESS_KEY",
+    "KSADK_SKILL_SERVICE_SECRET_KEY",
+    "KSADK_SKILL_SERVICE_ACCOUNT_ID",
+    "KSADK_SKILL_SERVICE_REGION",
+    "KSADK_SKILL_SERVICE_API_VERSION",
+    "KSADK_SKILL_SERVICE_SIGN_SERVICE",
+    "KSADK_SKILL_CACHE_DIR",
+    "KSADK_SKILL_WORKDIR",
+    "KSADK_SKILL_ARTIFACT_PROJECT",
+    "KSADK_PUBLIC_SKILL_SPACE_IDS",
+    "KSADK_PUBLIC_SKILL_ALLOWLIST",
+)
+
+_SKILL_SERVICE_SECRET_FALLBACKS = {
+    "KSADK_SKILL_SERVICE_ACCESS_KEY": ("KSYUN_ACCESS_KEY", "KS3_ACCESS_KEY"),
+    "KSADK_SKILL_SERVICE_SECRET_KEY": ("KSYUN_SECRET_KEY", "KS3_SECRET_KEY"),
+}
+
+
+def resolve_skill_space_ids() -> list[str]:
+    return configured_skill_space_ids()
+
+
+def resolve_user_skill_space_ids() -> list[str]:
+    return user_skill_space_ids()
+
+
+def _parse_skill_space_ids(*raw_values: str) -> list[str]:
+    return parse_skill_space_ids(*raw_values)
+
+
+def runtime_agent_env_from_process(skill_space_ids: list[str] | None = None) -> dict[str, str]:
+    env = {
+        name: value
+        for name in RUNTIME_AGENT_ENV_NAMES
+        if (value := os.environ.get(name))
+    }
+    if "KSADK_SKILL_SERVICE_ACCOUNT_ID" not in env and (
+        account_id := os.environ.get("KSYUN_ACCOUNT_ID")
+    ):
+        env["KSADK_SKILL_SERVICE_ACCOUNT_ID"] = account_id
+    if "KSADK_SKILL_SERVICE_REGION" not in env and (region := os.environ.get("KSYUN_REGION")):
+        env["KSADK_SKILL_SERVICE_REGION"] = region
+    has_spaces = bool(skill_space_ids) or bool(resolve_skill_space_ids())
+    if has_spaces:
+        for target, sources in _SKILL_SERVICE_SECRET_FALLBACKS.items():
+            if target in env:
+                continue
+            for source in sources:
+                value = os.environ.get(source, "").strip()
+                if value:
+                    env[target] = value
+                    break
+    if has_spaces and should_resolve_child_skill_service_url() and "KSADK_SKILL_SERVICE_URL" not in env:
+        service_url = resolve_skill_service_url(require_spaces=False)
+        if service_url:
+            env["KSADK_SKILL_SERVICE_URL"] = service_url
+    return env
+
+
+def build_execute_skills_tool(
+    *,
+    backend: SkillRuntimeBackend,
+    skill_space_ids: list[str] | None = None,
+    session_id: str | None = None,
+):
+    spaces = list(skill_space_ids or resolve_user_skill_space_ids())
+    default_session_id = session_id or f"ksadk-{uuid4().hex}"
+
+    def execute_skills(workflow_prompt: str, skill_names: list[str] | str | None = None) -> dict:
+        """Execute a workflow with the configured Skill Runtime."""
+
+        result = backend.run_workflow(
+            workflow_prompt,
+            skill_space_ids=spaces,
+            skill_names=normalize_skill_names(skill_names),
+            session_id=default_session_id,
+            env=runtime_agent_env_from_process(spaces),
+            timeout=int(os.environ.get("KSADK_SKILL_RUNTIME_TIMEOUT", "900")),
+        )
+        return result.to_dict()
+
+    execute_skills.__name__ = "execute_skills"
+    return execute_skills
+
+
+def load_remote_skill_manifests(skill_space_ids: list[str] | None = None) -> list[dict[str, str]]:
+    spaces = list(skill_space_ids or resolve_skill_space_ids())
+    public_spaces = set(public_skill_space_ids())
+    user_spaces = [space_id for space_id in spaces if space_id not in public_spaces]
+    if not user_spaces and not public_spaces:
+        return []
+
+    service_url = resolve_skill_service_url(require_spaces=True)
+    if not service_url:
+        return []
+
+    client = SkillServiceClient(
+        base_url=service_url,
+        token=os.environ.get("KSADK_SKILL_SERVICE_TOKEN", ""),
+        timeout=float(os.environ.get("KSADK_SKILL_MANIFEST_TIMEOUT", "5")),
+    )
+    manifests: list[dict[str, str]] = []
+    seen: set[str] = set()
+    limit = _manifest_limit()
+    public_allowlist = {
+        name.lower() for name in normalize_skill_names(os.environ.get("KSADK_PUBLIC_SKILL_ALLOWLIST", ""))
+    }
+    for space_id in user_spaces:
+        listing = client.list_skills_by_space_id(space_id)
+        for skill in listing.active_skills():
+            item = _skill_manifest_item(skill, space_id=space_id)
+            name_key = item["name"].lower()
+            if not item["name"] or name_key in seen:
+                continue
+            seen.add(name_key)
+            manifests.append(item)
+            if len(manifests) >= limit:
+                return manifests
+    if public_spaces:
+        listing = client.list_available_premade_skills()
+        for skill in listing.active_skills():
+            if public_allowlist and skill.name.lower() not in public_allowlist:
+                continue
+            item = _skill_manifest_item(skill, space_id=listing.space_id or "public")
+            name_key = item["name"].lower()
+            if not item["name"] or name_key in seen:
+                continue
+            seen.add(name_key)
+            manifests.append(item)
+            if len(manifests) >= limit:
+                return manifests
+    return manifests
+
+
+def build_skill_manifest_instruction(manifests: list[dict[str, str]]) -> str:
+    if not manifests:
+        return ""
+
+    lines = [
+        "",
+        "Available remote skills are listed below. Use them only when they match the user's task.",
+        "When a skill is useful, call execute_skills with the original workflow_prompt and skill_names set to the exact skill name.",
+        "Do not assume full skill instructions are already loaded; execute_skills loads selected skills on demand.",
+        "",
+        "Remote skills:",
+    ]
+    for item in manifests:
+        description = item.get("description") or "No description"
+        version = item.get("version") or ""
+        suffix = f" ({version})" if version else ""
+        lines.append(f"- {item['name']}{suffix}: {description}")
+    return "\n".join(lines)
+
+
+def _skill_manifest_item(skill: SkillRef, *, space_id: str) -> dict[str, str]:
+    item = {
+        "name": str(skill.name or "").strip(),
+        "description": _single_line(skill.description),
+        "version": str(skill.version or "").strip(),
+        "space_id": str(space_id or "").strip(),
+    }
+    if skill.aliases:
+        item["aliases"] = _single_line(", ".join(skill.aliases))
+    if skill.tags:
+        item["tags"] = _single_line(", ".join(skill.tags))
+    return item
+
+
+def _single_line(value: str, *, limit: int = 240) -> str:
+    text = " ".join(str(value or "").split())
+    return text[:limit].rstrip()
+
+
+def _manifest_limit() -> int:
+    try:
+        return max(1, int(os.environ.get("KSADK_SKILL_MANIFEST_LIMIT", "30")))
+    except ValueError:
+        return 30
+
+
+def build_skills_tool(skills: list[LocalSkill]):
+    def skills_tool(action: str = "list") -> dict:
+        """List locally loaded skills and their instructions."""
+
+        return {
+            "action": action,
+            "skills": [
+                {
+                    "name": skill.name,
+                    "description": skill.description,
+                    "body": skill.body,
+                    "root_dir": str(skill.root_dir),
+                }
+                for skill in skills
+            ],
+        }
+
+    skills_tool.__name__ = "skills_tool"
+    return skills_tool

ksadk/terminal_client.py

@@ -0,0 +1,69 @@
+"""通用远程终端 websocket client。
+
+当前 Hermes 与 OpenClaw runtime proxy 都使用同一套 `ks-terminal.v1`
+协议。Hermes 仍保留 `ksadk.hermes_terminal` 的兼容入口；新框架应优先
+引用本模块，避免把协议命名绑定到某一个框架。
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Sequence
+
+from ksadk.hermes_terminal import (
+    TERMINAL_SUBPROTOCOL,
+    TERMINAL_WS_PATH,
+    TerminalSize,
+    build_start_frame,
+    build_terminal_exec_validator,
+    build_terminal_ws_url,
+    detect_terminal_size,
+    run_hermes_terminal_session,
+    validate_terminal_exec_argv,
+)
+from ksadk.terminal_exec_policy import GENERIC_TERMINAL_EXEC_POLICY, TerminalExecPolicy
+
+
+async def run_terminal_session(
+    *,
+    endpoint: str,
+    api_key: str | None = None,
+    session_id: str | None = None,
+    insecure: bool = False,
+    mode: str = "tui",
+    argv: Sequence[str] | None = None,
+    cwd: str | None = None,
+    options: Mapping[str, Any] | None = None,
+    exec_policy: TerminalExecPolicy | None = None,
+    stdin: Any | None = None,
+    stdout: Any | None = None,
+) -> int:
+    """Attach to a framework-native terminal session over ks-terminal.v1."""
+
+    return await run_hermes_terminal_session(
+        endpoint=endpoint,
+        api_key=api_key,
+        session_id=session_id,
+        insecure=insecure,
+        mode=mode,
+        argv=argv,
+        cwd=cwd,
+        options=options,
+        stdin=stdin,
+        stdout=stdout,
+        exec_argv_validator=(
+            build_terminal_exec_validator(exec_policy)
+            if exec_policy is not None and exec_policy != GENERIC_TERMINAL_EXEC_POLICY
+            else validate_terminal_exec_argv
+        ),
+    )
+
+
+__all__ = [
+    "TERMINAL_SUBPROTOCOL",
+    "TERMINAL_WS_PATH",
+    "TerminalSize",
+    "build_start_frame",
+    "build_terminal_ws_url",
+    "detect_terminal_size",
+    "run_terminal_session",
+]

ksadk/terminal_exec_policy.py

@@ -0,0 +1,229 @@
+"""Shared remote terminal exec command policy."""
+
+from __future__ import annotations
+
+import os
+import re
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+
+SHELL_METACHARS = set("|&;<>()$`\\\n\r")
+FORBIDDEN_LAUNCHERS = {
+    "bash",
+    "sh",
+    "zsh",
+    "fish",
+    "python",
+    "python3",
+    "node",
+    "npx",
+    "pnpm",
+    "npm",
+    "yarn",
+    "uv",
+    "uvx",
+    "hermes",
+}
+
+TERMINAL_EXEC_ALLOWLIST_ENV = "KSADK_TERMINAL_EXEC_SUBCOMMAND_ALLOWLIST"
+
+COMMON_REMOTE_EXEC_PREFIXES: tuple[tuple[str, ...], ...] = (
+    ("cat",),
+    ("date",),
+    ("df",),
+    ("du",),
+    ("find",),
+    ("git", "diff"),
+    ("git", "log"),
+    ("git", "rev-parse"),
+    ("git", "show"),
+    ("git", "status"),
+    ("head",),
+    ("id",),
+    ("ls",),
+    ("ps",),
+    ("pwd",),
+    ("stat",),
+    ("tail",),
+    ("uname",),
+    ("wc",),
+    ("whoami",),
+)
+
+
+@dataclass(frozen=True)
+class TerminalExecPolicy:
+    name: str
+    default_exact: tuple[tuple[str, ...], ...] = ()
+    default_prefixes: tuple[tuple[str, ...], ...] = ()
+    default_bounded_prefixes: tuple[tuple[tuple[str, ...], int, int], ...] = ()
+    env_names: tuple[str, ...] = (TERMINAL_EXEC_ALLOWLIST_ENV,)
+
+
+GENERIC_TERMINAL_EXEC_POLICY = TerminalExecPolicy(
+    name="terminal",
+    default_prefixes=COMMON_REMOTE_EXEC_PREFIXES,
+)
+
+HERMES_TERMINAL_EXEC_POLICY = TerminalExecPolicy(
+    name="Hermes",
+    default_exact=(
+        ("cron", "list"),
+        ("cron", "status"),
+        ("config", "check"),
+        ("config", "env-path"),
+        ("config", "path"),
+        ("config", "show"),
+        ("doctor",),
+        ("gateway", "status"),
+        ("insights",),
+        ("sessions", "list"),
+        ("skills", "audit"),
+        ("skills", "check"),
+        ("skills", "list"),
+        ("status",),
+        ("tools", "list"),
+        ("version",),
+    ),
+    default_bounded_prefixes=(
+        (("sessions", "export"), 3, 3),
+        (("sessions", "show"), 3, 3),
+    ),
+)
+
+OPENCLAW_TERMINAL_EXEC_POLICY = TerminalExecPolicy(
+    name="OpenClaw",
+    default_prefixes=(
+        *COMMON_REMOTE_EXEC_PREFIXES,
+        ("openclaw", "channels", "login"),
+    ),
+)
+
+_ALLOWLIST_ENTRY_SPLIT_RE = re.compile(r"[\n;,]+")
+_ALLOWLIST_TOKEN_SPLIT_RE = re.compile(r"\s+")
+
+
+def normalize_exec_argv(
+    argv: Iterable[str],
+    *,
+    policy_name: str = "terminal",
+    allow_shell_metachars: bool = False,
+    allow_forbidden_launchers: bool = False,
+) -> list[str]:
+    normalized = [str(item).strip() for item in argv]
+    if not normalized:
+        raise ValueError(f"{policy_name} exec requires argv")
+    for index, item in enumerate(normalized):
+        if not item:
+            raise ValueError(f"{policy_name} exec argv contains an empty argument")
+        if not allow_shell_metachars and any(char in SHELL_METACHARS for char in item):
+            raise ValueError(f"{policy_name} exec does not allow shell metacharacters: {item}")
+        if index == 0 and item.startswith("-"):
+            raise ValueError(f"{policy_name} exec command is invalid: {item}")
+        if not allow_forbidden_launchers and index == 0 and item in FORBIDDEN_LAUNCHERS:
+            raise ValueError(f"{policy_name} exec launcher is not allowed: {item}")
+    return normalized
+
+
+def validate_terminal_exec_argv(
+    argv: Iterable[str],
+    *,
+    policy: TerminalExecPolicy = GENERIC_TERMINAL_EXEC_POLICY,
+) -> list[str]:
+    if _env_allowlist_all(policy.env_names):
+        return normalize_exec_argv(
+            argv,
+            policy_name=policy.name,
+            allow_shell_metachars=True,
+            allow_forbidden_launchers=True,
+        )
+
+    normalized = normalize_exec_argv(argv, policy_name=policy.name)
+    allowed_exact = tuple(tuple(item) for item in policy.default_exact)
+    allowed_prefixes = (
+        tuple(tuple(item) for item in policy.default_prefixes)
+        + _env_allowlist_prefixes(policy.env_names, policy_name=policy.name)
+    )
+
+    if _matches_exact_or_prefix(
+        normalized,
+        allowed_exact=allowed_exact,
+        allowed_prefixes=allowed_prefixes,
+        allowed_bounded_prefixes=policy.default_bounded_prefixes,
+    ):
+        return normalized
+    suggested_prefix = normalized[0]
+    raise ValueError(
+        f"{policy.name} exec subcommand is not allowed: {' '.join(normalized)}. "
+        f"Set {TERMINAL_EXEC_ALLOWLIST_ENV}='{suggested_prefix}' to allow this prefix, "
+        f"or {TERMINAL_EXEC_ALLOWLIST_ENV}='*' to allow all remote exec commands."
+    )
+
+
+def _env_allowlist_prefixes(
+    env_names: Sequence[str],
+    *,
+    policy_name: str,
+) -> tuple[tuple[str, ...], ...]:
+    prefixes: list[tuple[str, ...]] = []
+    seen: set[tuple[str, ...]] = set()
+    for env_name in env_names:
+        for prefix in _parse_allowlist_prefixes(os.getenv(env_name), policy_name=policy_name):
+            if prefix not in seen:
+                prefixes.append(prefix)
+                seen.add(prefix)
+    return tuple(prefixes)
+
+
+def _env_allowlist_all(env_names: Sequence[str]) -> bool:
+    for env_name in env_names:
+        raw = os.getenv(env_name)
+        if not raw:
+            continue
+        for entry in _ALLOWLIST_ENTRY_SPLIT_RE.split(raw):
+            if entry.strip() == "*":
+                return True
+    return False
+
+
+def _parse_allowlist_prefixes(raw: str | None, *, policy_name: str) -> tuple[tuple[str, ...], ...]:
+    if not raw:
+        return ()
+    prefixes: list[tuple[str, ...]] = []
+    for entry in _ALLOWLIST_ENTRY_SPLIT_RE.split(raw):
+        entry = entry.strip()
+        if not entry:
+            continue
+        if entry == "*":
+            continue
+        tokens = tuple(token for token in _ALLOWLIST_TOKEN_SPLIT_RE.split(entry) if token)
+        normalize_exec_argv(tokens, policy_name=policy_name)
+        prefixes.append(tokens)
+    return tuple(prefixes)
+
+
+def _matches_exact_or_prefix(
+    argv: Sequence[str],
+    *,
+    allowed_exact: Sequence[Sequence[str]],
+    allowed_prefixes: Sequence[Sequence[str]],
+    allowed_bounded_prefixes: Sequence[tuple[Sequence[str], int, int]],
+) -> bool:
+    argv_tuple = tuple(argv)
+    for item in allowed_exact:
+        if argv_tuple == tuple(item):
+            return True
+    for prefix in allowed_prefixes:
+        prefix_tuple = tuple(prefix)
+        if prefix_tuple and argv_tuple[: len(prefix_tuple)] == prefix_tuple:
+            return True
+    for prefix, min_len, max_len in allowed_bounded_prefixes:
+        prefix_tuple = tuple(prefix)
+        if (
+            prefix_tuple
+            and argv_tuple[: len(prefix_tuple)] == prefix_tuple
+            and len(argv_tuple) >= min_len
+            and len(argv_tuple) <= max_len
+        ):
+            return True
+    return False

ksadk/tools/__init__.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from ksadk.tools.gateway import (
+    ToolGateway,
+    ToolPolicy,
+    approval_interrupt_info_from_result,
+    check_command_policy,
+    default_tool_gateway,
+)
+
+__all__ = [
+    "ToolGateway",
+    "ToolPolicy",
+    "approval_interrupt_info_from_result",
+    "check_command_policy",
+    "default_tool_gateway",
+]