apsimo 1.3.0__py3-none-any.whl

apsimo/skills/loader.py

@@ -0,0 +1,246 @@
+"""Colony Skills — on-demand skill module loader."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import hmac
+import importlib
+import importlib.util
+import logging
+import types
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from apsimo.skills.budget import ContextBudget
+from apsimo.skills.index import SkillEntry, SkillIndex
+
+logger = logging.getLogger(__name__)
+
+
+class SecurityError(Exception):
+    """Raised when a skill integrity or security check fails."""
+
+
+class SchemaError(Exception):
+    """Raised when a skill entry is missing required schema fields."""
+
+
+# Only modules under these prefixes may be loaded via lazy_loader
+_ALLOWED_LAZY_LOADER_PREFIXES = frozenset({"colony.skills.", "colony.plugins."})
+
+
+def _verify_skill_checksum(skill_path: Path, expected_sha256: str) -> bytes:
+    """Verify SHA-256 of skill_path matches expected_sha256 before execution.
+
+    Returns the file bytes so the caller can compile from memory without a
+    second disk read, eliminating the TOCTOU window (SEC-14-C-03).
+
+    Raises:
+        SecurityError: If checksum is missing or does not match.
+    """
+    if not expected_sha256:
+        raise SecurityError(
+            "SkillEntry has no checksum — cannot load unverified skill"
+        )
+    file_bytes = skill_path.read_bytes()
+    actual = hashlib.sha256(file_bytes).hexdigest()
+    if not hmac.compare_digest(actual, expected_sha256):
+        raise SecurityError(
+            f"Skill checksum mismatch for {skill_path}: "
+            f"expected {expected_sha256!r}, got {actual!r}"
+        )
+    return file_bytes
+
+
+@dataclass
+class LoadedSkill:
+    """A skill that has been imported and is resident in memory."""
+
+    entry: SkillEntry
+    module: types.ModuleType
+    loaded_at: datetime
+    last_used_at: datetime
+    use_count: int = 0
+
+
+class SkillLoader:
+    """Imports and initializes skill modules on demand.
+
+    Maintains a loaded-skill cache keyed by skill_id.
+    """
+
+    def __init__(self, index: SkillIndex) -> None:
+        self._index = index
+        self._loaded: Dict[str, LoadedSkill] = {}
+        self._lock = asyncio.Lock()
+
+    async def load(self, skill_id: str) -> Optional[LoadedSkill]:
+        """Import the skill module if not already loaded.
+
+        Records load timestamp for LRU eviction.
+        Returns None if the skill is not in the index.
+        """
+        async with self._lock:
+            if skill_id in self._loaded:
+                ls = self._loaded[skill_id]
+                ls.last_used_at = datetime.now(timezone.utc)
+                ls.use_count += 1
+                return ls
+
+            entry = self._index.get(skill_id)
+            if entry is None:
+                logger.warning("SkillLoader.load: skill %r not in index", skill_id)
+                return None
+
+            module = await self._import_module(entry)
+            if module is None:
+                return None
+
+            # Call initialize() hook if present
+            init_fn = getattr(module, "initialize", None)
+            if init_fn is not None:
+                try:
+                    if asyncio.iscoroutinefunction(init_fn):
+                        await init_fn()
+                    else:
+                        init_fn()
+                except Exception as exc:
+                    logger.warning("Skill %s initialize() failed: %s", skill_id, exc)
+
+            now = datetime.now(timezone.utc)
+            ls = LoadedSkill(
+                entry=entry,
+                module=module,
+                loaded_at=now,
+                last_used_at=now,
+                use_count=1,
+            )
+            self._loaded[skill_id] = ls
+            logger.debug("SkillLoader: loaded skill %s", skill_id)
+            return ls
+
+    async def unload(self, skill_id: str) -> None:
+        """Remove skill from loaded cache.
+
+        Does NOT clean up sys.modules (Python limitation), but clears the
+        in-context reference so the agent no longer sees it.
+        """
+        async with self._lock:
+            self._loaded.pop(skill_id, None)
+        logger.debug("SkillLoader: unloaded skill %s", skill_id)
+
+    async def load_for_event(
+        self, text: str, budget: ContextBudget
+    ) -> List[LoadedSkill]:
+        """Match text against index, load matched skills within budget.
+
+        Returns list of all loaded skills relevant to the event (including
+        already-loaded ones). Already-loaded skills do not consume budget again.
+        """
+        candidates = self._index.match(text)
+        result: List[LoadedSkill] = []
+        current_used = self.token_footprint()
+
+        for entry in candidates:
+            if entry.skill_id in self._loaded:
+                ls = self._loaded[entry.skill_id]
+                ls.last_used_at = datetime.now(timezone.utc)
+                ls.use_count += 1
+                result.append(ls)
+            elif budget.has_capacity(entry.context_tokens_estimate, current_used):
+                ls = await self.load(entry.skill_id)
+                if ls is not None:
+                    result.append(ls)
+                    current_used += entry.context_tokens_estimate
+            else:
+                logger.debug(
+                    "SkillLoader: budget full, skipping skill %s (needs %d, available %d)",
+                    entry.skill_id,
+                    entry.context_tokens_estimate,
+                    budget.tokens_available(current_used),
+                )
+
+        return result
+
+    def loaded_ids(self) -> List[str]:
+        """Return skill_ids currently in the loaded cache."""
+        return list(self._loaded.keys())
+
+    def token_footprint(self) -> int:
+        """Sum of context_tokens_estimate for all loaded skills."""
+        return sum(ls.entry.context_tokens_estimate for ls in self._loaded.values())
+
+    def get_loaded(self, skill_id: str) -> Optional[LoadedSkill]:
+        """Return a loaded skill by ID, or None."""
+        return self._loaded.get(skill_id)
+
+    def all_loaded(self) -> List[LoadedSkill]:
+        """Return all currently loaded skills."""
+        return list(self._loaded.values())
+
+    @staticmethod
+    async def _import_module(entry: SkillEntry) -> Optional[types.ModuleType]:
+        """Import skill module using lazy_loader or default file-based import."""
+        if entry.lazy_loader:
+            # Dotted import path: "some.module:factory_fn" — allowlist enforced
+            try:
+                parts = entry.lazy_loader.split(":", 1)
+                mod_path = parts[0]
+                fn_name = parts[1] if len(parts) > 1 else None
+
+                if not any(mod_path.startswith(p) for p in _ALLOWED_LAZY_LOADER_PREFIXES):
+                    raise SecurityError(
+                        f"Disallowed lazy_loader module: {mod_path!r}"
+                    )
+                if fn_name is not None and not fn_name.isidentifier():
+                    raise SecurityError(
+                        f"Invalid function name in lazy_loader: {fn_name!r}"
+                    )
+
+                mod = importlib.import_module(mod_path)
+                if fn_name:
+                    fn = getattr(mod, fn_name)
+                    result = fn(entry)
+                    if asyncio.iscoroutine(result):
+                        return await result
+                    return result
+                return mod
+            except SecurityError:
+                raise
+            except Exception as exc:
+                logger.error(
+                    "Skill %s: lazy_loader %r failed: %s", entry.skill_id, entry.lazy_loader, exc
+                )
+                return None
+
+        # Default: load skill.py from skill_dir
+        skill_path = entry.skill_dir / "skill.py"
+        if not skill_path.exists():
+            logger.warning("Skill %s: no skill.py at %s", entry.skill_id, skill_path)
+            return None
+
+        try:
+            # Read once, verify checksum, compile from memory — no second disk read
+            # eliminates the TOCTOU window (SEC-14-C-03)
+            if not hasattr(entry, "checksum_sha256"):
+                raise SchemaError(
+                    f"SkillEntry for {entry.skill_id!r} is missing required "
+                    f"'checksum_sha256' field — refusing to load unverified skill"
+                )
+            file_bytes = _verify_skill_checksum(skill_path, entry.checksum_sha256)
+
+            # Compile and execute from the already-verified in-memory bytes
+            code = compile(file_bytes, str(skill_path), "exec")
+            module = types.ModuleType(f"_skill_{entry.skill_id}")
+            module.__file__ = str(skill_path)
+            module.__spec__ = None
+            exec(code, module.__dict__)  # noqa: S102  # nosec B102  # bytes already verified above
+            return module
+        except (SecurityError, SchemaError):
+            raise
+        except Exception as exc:
+            logger.error("Skill %s: import from %s failed: %s", entry.skill_id, skill_path, exc)
+            return None

apsimo/skills/migrations/002_progressive_loading.sql

@@ -0,0 +1,6 @@
+-- Migration 002: progressive skill loading columns
+-- Safe to run on existing databases; columns added only if absent.
+
+ALTER TABLE skills ADD COLUMN trigger_patterns TEXT NOT NULL DEFAULT '[]';
+ALTER TABLE skills ADD COLUMN context_tokens_estimate INTEGER NOT NULL DEFAULT 2048;
+ALTER TABLE skills ADD COLUMN lazy_loader TEXT;

apsimo/skills/migrations/backfill_triggers.py

@@ -0,0 +1,20 @@
+"""Backfill trigger_patterns for existing skills from their name and tags.
+
+NOTE: This migration was written for a legacy SQLite-backed SkillRegistry.
+The current SkillRegistry is in-memory and auto-loads built-in skills.
+This script is kept for historical reference but is a no-op.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+def backfill(db_path: Path) -> None:
+    print("INFO: Legacy migration skipped — current SkillRegistry is in-memory.")
+
+
+if __name__ == "__main__":
+    db = Path(sys.argv[1]) if len(sys.argv) > 1 else Path("~/.colony/skills.db").expanduser()
+    backfill(db)

apsimo/skills/models.py

@@ -0,0 +1,202 @@
+"""Colony Skills — data models for the self-creating skills subsystem."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Dict, List, Optional, Set
+
+
+class SkillStatus(str, Enum):
+    DRAFT = "draft"
+    ACTIVE = "active"
+    INACTIVE = "inactive"
+    QUARANTINED = "quarantined"
+    DEPRECATED = "deprecated"
+    ARCHIVED = "archived"
+
+
+class SkillCapability(str, Enum):
+    """Capabilities a skill may declare. All are deny-by-default."""
+    NETWORK = "network"
+    FILESYSTEM_READ = "fs_read"
+    FILESYSTEM_WRITE = "fs_write"
+    SUBPROCESS = "subprocess"
+    ENV_READ = "env_read"
+    LLM_CALL = "llm_call"
+    TASK_POST = "task_post"
+    FEDERATION_EMIT = "fed_emit"
+
+
+@dataclass
+class SkillPermissions:
+    """Declared resource access for a skill."""
+    capabilities: List[SkillCapability] = field(default_factory=list)
+    allowed_domains: List[str] = field(default_factory=list)
+    allowed_read_paths: List[str] = field(default_factory=list)
+    allowed_write_paths: List[str] = field(default_factory=list)
+    allowed_env_vars: List[str] = field(default_factory=list)
+    allowed_imports: List[str] = field(default_factory=list)
+    max_duration_secs: int = 60
+    max_memory_mb: int = 256
+
+
+@dataclass
+class SkillManifest:
+    """Complete metadata for a Colony skill.
+
+    Stored as colony.skill.json alongside the skill source.
+    """
+    skill_id: str
+    name: str
+    version: str
+    description: str
+    author_colony_id: str
+    created_at: datetime
+    updated_at: datetime
+    status: SkillStatus = SkillStatus.DRAFT
+    entry_point: str = "skill:run"
+    permissions: SkillPermissions = field(default_factory=SkillPermissions)
+    tags: List[str] = field(default_factory=list)
+    dependencies: List[str] = field(default_factory=list)
+    input_schema: Dict[str, Any] = field(default_factory=dict)
+    output_schema: Dict[str, Any] = field(default_factory=dict)
+    checksum_sha256: str = ""
+    # Empty string means "no checksum recorded" (e.g. MCP-bridged or legacy skills).
+    # Any execution path that verifies integrity MUST reject an empty value — it is
+    # not a valid hash.  See SkillExecutor._run_skill() which raises SecurityError
+    # when this field is falsy.
+    origin_task_id: Optional[str] = None
+    parent_skill_id: Optional[str] = None
+    trust_score: float = 0.0
+    execution_count: int = 0
+    last_executed_at: Optional[datetime] = None
+    signature: str = ""
+    skill_dir: Optional[str] = None
+    # MCP bridge fields — None for native skills
+    origin: Optional[str] = None       # "mcp" for MCP-bridged tools
+    mcp_server: Optional[str] = None   # server name (e.g. "github")
+    mcp_tool: Optional[str] = None     # original tool name on the server
+
+    # Progressive loading additions
+    trigger_patterns: List[str] = field(default_factory=list)
+    context_tokens_estimate: int = 2048
+    lazy_loader: Optional[str] = None
+
+    def compute_checksum(self, source_code: str) -> str:
+        """Compute and store SHA-256 checksum of skill source."""
+        digest = hashlib.sha256(source_code.encode()).hexdigest()
+        self.checksum_sha256 = digest
+        return digest
+
+    def to_json(self) -> str:
+        """Serialize to JSON for storage as colony.skill.json."""
+        d = {
+            "skill_id": self.skill_id,
+            "name": self.name,
+            "version": self.version,
+            "description": self.description,
+            "author_colony_id": self.author_colony_id,
+            "created_at": self.created_at.isoformat(),
+            "updated_at": self.updated_at.isoformat(),
+            "status": self.status.value,
+            "entry_point": self.entry_point,
+            "permissions": {
+                "capabilities": [c.value for c in self.permissions.capabilities],
+                "allowed_domains": self.permissions.allowed_domains,
+                "allowed_read_paths": self.permissions.allowed_read_paths,
+                "allowed_write_paths": self.permissions.allowed_write_paths,
+                "allowed_env_vars": self.permissions.allowed_env_vars,
+                "max_duration_secs": self.permissions.max_duration_secs,
+                "max_memory_mb": self.permissions.max_memory_mb,
+            },
+            "tags": self.tags,
+            "dependencies": self.dependencies,
+            "input_schema": self.input_schema,
+            "output_schema": self.output_schema,
+            "checksum_sha256": self.checksum_sha256,
+            "origin_task_id": self.origin_task_id,
+            "parent_skill_id": self.parent_skill_id,
+            "trust_score": self.trust_score,
+            "execution_count": self.execution_count,
+            "signature": self.signature,
+            "trigger_patterns": self.trigger_patterns,
+            "context_tokens_estimate": self.context_tokens_estimate,
+            "lazy_loader": self.lazy_loader,
+            "origin": self.origin,
+            "mcp_server": self.mcp_server,
+            "mcp_tool": self.mcp_tool,
+        }
+        return json.dumps(d, indent=2, sort_keys=True)
+
+    @classmethod
+    def from_json(cls, raw: str) -> "SkillManifest":
+        """Deserialize from JSON."""
+        d = json.loads(raw)
+        perms_raw = d.get("permissions", {})
+        perms = SkillPermissions(
+            capabilities=[SkillCapability(c) for c in perms_raw.get("capabilities", [])],
+            allowed_domains=perms_raw.get("allowed_domains", []),
+            allowed_read_paths=perms_raw.get("allowed_read_paths", []),
+            allowed_write_paths=perms_raw.get("allowed_write_paths", []),
+            allowed_env_vars=perms_raw.get("allowed_env_vars", []),
+            max_duration_secs=perms_raw.get("max_duration_secs", 60),
+            max_memory_mb=perms_raw.get("max_memory_mb", 256),
+        )
+        return cls(
+            skill_id=d["skill_id"],
+            name=d["name"],
+            version=d["version"],
+            description=d["description"],
+            author_colony_id=d["author_colony_id"],
+            created_at=datetime.fromisoformat(d["created_at"]),
+            updated_at=datetime.fromisoformat(d["updated_at"]),
+            status=SkillStatus(d.get("status", "draft")),
+            entry_point=d.get("entry_point", "skill:run"),
+            permissions=perms,
+            tags=d.get("tags", []),
+            dependencies=d.get("dependencies", []),
+            input_schema=d.get("input_schema", {}),
+            output_schema=d.get("output_schema", {}),
+            checksum_sha256=d.get("checksum_sha256", ""),
+            origin_task_id=d.get("origin_task_id"),
+            parent_skill_id=d.get("parent_skill_id"),
+            trust_score=d.get("trust_score", 0.0),
+            execution_count=d.get("execution_count", 0),
+            signature=d.get("signature", ""),
+            trigger_patterns=d.get("trigger_patterns", []),
+            context_tokens_estimate=d.get("context_tokens_estimate", 2048),
+            lazy_loader=d.get("lazy_loader"),
+            origin=d.get("origin"),
+            mcp_server=d.get("mcp_server"),
+            mcp_tool=d.get("mcp_tool"),
+        )
+
+
+@dataclass
+class TaskSolution:
+    """A completed task solution that may be captured as a skill."""
+    task_id: str
+    task_description: str
+    inputs: Dict[str, Any]
+    output: Any
+    trace: List[Dict[str, Any]]
+    dependencies: List[str]
+    embedding: Optional[List[float]]
+    step_fingerprint: Optional[List[str]]
+    duration_secs: float
+    completed_at: datetime
+
+
+@dataclass
+class SkillSummary:
+    """Lightweight skill summary for novelty scoring and search."""
+    skill_id: str
+    description: str
+    tags: List[str]
+    dependencies: List[str]
+    embedding: Optional[List[float]] = None
+    step_fingerprint: Optional[List[str]] = None

apsimo/skills/packager.py

@@ -0,0 +1,128 @@
+"""Colony Skills — packaging extracted patterns as skill directories."""
+
+from __future__ import annotations
+
+import logging
+import pathlib
+import re
+import uuid
+from datetime import datetime, timezone
+from typing import Optional
+
+from apsimo.skills.learning.pattern_extractor import ExtractedPattern
+from apsimo.skills.learning.triggers import TriggerSource
+from apsimo.skills.models import SkillCapability, SkillManifest, SkillPermissions, SkillStatus
+from apsimo.skills.registry import SkillRegistry
+
+logger = logging.getLogger(__name__)
+
+_SLUG_RE = re.compile(r"[^a-z0-9-]")
+_SKILL_LIBRARY_PATH = pathlib.Path("colony/skills/library")
+
+
+class SkillPackager:
+    """Packages an ExtractedPattern into a skill directory and registers it."""
+
+    def __init__(
+        self,
+        registry: SkillRegistry,
+        colony_id: str,
+        library_root: pathlib.Path = _SKILL_LIBRARY_PATH,
+    ) -> None:
+        self._registry = registry
+        self._colony_id = colony_id
+        self._library = library_root
+
+    async def package(
+        self,
+        solution: "TaskSolution",  # noqa: F821
+        pattern: ExtractedPattern,
+        source: TriggerSource,
+    ) -> str:
+        """Create a skill directory from an extracted pattern.
+
+        Returns:
+            The new skill_id string.
+        """
+        now = datetime.now(timezone.utc)
+        slug = self._slugify(solution.task_description[:48])
+        uid = uuid.uuid4().hex[:8]
+        skill_id = f"{slug}_{uid}"
+        version = "1.0.0"
+        skill_dir = self._library / f"{skill_id}_v{version}"
+        skill_dir.mkdir(parents=True, exist_ok=True)
+
+        permissions = self._build_permissions(pattern)
+        manifest = SkillManifest(
+            skill_id=skill_id,
+            name=slug.replace("-", " ").title(),
+            version=version,
+            description=pattern.docstring.split("\n")[0],
+            author_colony_id=self._colony_id,
+            created_at=now,
+            updated_at=now,
+            status=SkillStatus.DRAFT,
+            entry_point="skill:run",
+            permissions=permissions,
+            tags=pattern.tags,
+            dependencies=pattern.dependencies,
+            input_schema=pattern.input_schema,
+            output_schema=pattern.output_schema,
+            origin_task_id=solution.task_id,
+            skill_dir=str(skill_dir),
+        )
+        manifest.compute_checksum(pattern.source_code)
+
+        (skill_dir / "skill.py").write_text(pattern.source_code, encoding="utf-8")
+        (skill_dir / "colony.skill.json").write_text(manifest.to_json(), encoding="utf-8")
+        (skill_dir / "requirements.txt").write_text(
+            "\n".join(pattern.dependencies), encoding="utf-8"
+        )
+        self._write_smoke_test(skill_dir, slug, pattern)
+
+        await self._registry.register(manifest, skill_dir)
+        logger.info("Packaged skill %s → %s", skill_id, skill_dir)
+        return skill_id
+
+    def _build_permissions(self, pattern: ExtractedPattern) -> SkillPermissions:
+        caps: list[SkillCapability] = []
+        if pattern.network_domains:
+            caps.append(SkillCapability.NETWORK)
+        if pattern.file_paths:
+            caps.append(SkillCapability.FILESYSTEM_READ)
+        if pattern.env_vars:
+            caps.append(SkillCapability.ENV_READ)
+        return SkillPermissions(
+            capabilities=caps,
+            allowed_domains=pattern.network_domains,
+            allowed_read_paths=pattern.file_paths,
+            allowed_env_vars=list(pattern.env_vars),
+        )
+
+    @staticmethod
+    def _slugify(text: str) -> str:
+        return _SLUG_RE.sub("-", text.lower().strip()).strip("-")[:48]
+
+    @staticmethod
+    def _write_smoke_test(
+        skill_dir: pathlib.Path, slug: str, pattern: ExtractedPattern
+    ) -> None:
+        fn_name = slug.replace("-", "_")
+        test_code = f"""\
+import pytest
+
+@pytest.mark.asyncio
+async def test_{fn_name}_runs():
+    # Smoke test: verify skill file exists and run() is callable.
+    import importlib.util
+    import pathlib
+    skill_path = pathlib.Path("{skill_dir}") / "skill.py"
+    if skill_path.exists():
+        spec = importlib.util.spec_from_file_location("_skill", skill_path)
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+        assert callable(getattr(module, "run", None))
+"""
+        tests_dir = skill_dir / "tests"
+        tests_dir.mkdir(exist_ok=True)
+        (tests_dir / "test_skill.py").write_text(test_code, encoding="utf-8")

apsimo/skills/protocols.py

@@ -0,0 +1,70 @@
+"""Colony Skills — typed Protocol interfaces for dependency injection."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Protocol, runtime_checkable
+
+from apsimo.skills.models import SkillManifest, SkillStatus
+from apsimo.skills.learning.novelty_detector import NoveltyResult
+from apsimo.skills.learning.pattern_extractor import ExtractedPattern
+from apsimo.skills.security.scanner import ASTScanResult
+from apsimo.skills.executor import ExecutionResult
+
+
+@runtime_checkable
+class ISkillRegistry(Protocol):
+    """Read/write interface to the skill registry."""
+
+    async def register(self, manifest: SkillManifest, skill_dir: Any) -> None: ...
+    async def get(self, skill_id: str) -> Optional[SkillManifest]: ...
+    async def search(
+        self,
+        query: str = "",
+        tags: Optional[List[str]] = None,
+        status: Optional[SkillStatus] = None,
+        limit: int = 50,
+    ) -> List[SkillManifest]: ...
+    async def activate(self, skill_id: str) -> None: ...
+    async def deactivate(self, skill_id: str) -> None: ...
+    async def quarantine(self, skill_id: str, reason: str) -> None: ...
+    async def list_summaries(self) -> List[Any]: ...
+
+
+@runtime_checkable
+class INoveltyDetector(Protocol):
+    """Scores how novel a task solution is relative to the skill registry."""
+
+    async def score(self, solution: Any) -> NoveltyResult: ...
+
+
+@runtime_checkable
+class IPatternExtractor(Protocol):
+    """Extracts a generalizable pattern from a task solution."""
+
+    def extract(self, solution: Any) -> ExtractedPattern: ...
+
+
+@runtime_checkable
+class ISkillPackager(Protocol):
+    """Packages an extracted pattern as a skill directory."""
+
+    async def package(self, solution: Any, pattern: ExtractedPattern, source: Any) -> str: ...
+
+
+@runtime_checkable
+class IASTScanner(Protocol):
+    """Statically analyzes skill Python source for security issues."""
+
+    def scan(self, source: str, skill_id: str) -> ASTScanResult: ...
+
+
+@runtime_checkable
+class ISkillExecutor(Protocol):
+    """Executes a skill by ID inside a capability-gated sandbox."""
+
+    async def invoke(
+        self,
+        skill_id: str,
+        inputs: Dict[str, Any],
+        caller_context: Optional[str] = None,
+    ) -> ExecutionResult: ...