apsimo 1.3.0__py3-none-any.whl

apsimo/skills/security/__init__.py

@@ -0,0 +1,12 @@
+"""Colony Skills — security layer (AST scanner and capability guards)."""
+
+from apsimo.skills.security.scanner import ASTScanner, ASTScanResult, ScanFinding
+from apsimo.skills.security.guards import CapabilityGuard, GuardResult
+
+__all__ = [
+    "ASTScanner",
+    "ASTScanResult",
+    "ScanFinding",
+    "CapabilityGuard",
+    "GuardResult",
+]

apsimo/skills/security/guards.py

@@ -0,0 +1,53 @@
+"""Colony Skills — capability guards for pre-execution checks."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List
+
+from apsimo.skills.models import SkillCapability, SkillManifest
+
+
+@dataclass
+class GuardResult:
+    allowed: bool
+    reason: str
+    violations: List[str] = field(default_factory=list)
+
+
+class CapabilityGuard:
+    """Pre-execution checks that enforce declared capability constraints.
+
+    Checks performed:
+      - Input parameters do not include path traversal sequences
+      - Network capability required if inputs reference external URLs
+      - Execution blocked entirely if skill is quarantined or inactive
+    """
+
+    async def check(
+        self, manifest: SkillManifest, inputs: Dict[str, Any]
+    ) -> GuardResult:
+        violations: List[str] = []
+
+        # Path traversal in string inputs
+        for key, value in inputs.items():
+            if isinstance(value, str) and ".." in value:
+                violations.append(f"Path traversal in input '{key}': {value[:80]}")
+
+        # Network capability required for URL inputs
+        has_url_input = any(
+            isinstance(v, str) and (v.startswith("http://") or v.startswith("https://"))
+            for v in inputs.values()
+        )
+        if has_url_input and SkillCapability.NETWORK not in manifest.permissions.capabilities:
+            violations.append(
+                "Input contains URL but skill does not declare NETWORK capability."
+            )
+
+        if violations:
+            return GuardResult(
+                allowed=False,
+                reason="Pre-execution guard failed.",
+                violations=violations,
+            )
+        return GuardResult(allowed=True, reason="All guards passed.")

apsimo/skills/security/scanner.py

@@ -0,0 +1,223 @@
+"""Colony Skills — Python AST-based static analysis for skill source code."""
+
+from __future__ import annotations
+
+import ast
+import hashlib
+import re
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+
+BLOCKED_BUILTINS = frozenset({
+    "exec", "eval", "compile", "__import__", "open",
+    "breakpoint", "input",
+})
+
+BLOCKED_MODULES = frozenset({
+    "subprocess", "os.system", "pty", "ctypes", "pickle",
+    "marshal", "importlib.util",
+})
+
+# Dunder attributes that reach the runtime's object graph and let a skill
+# escape the builtins allowlist via chains like
+# ``().__class__.__bases__[0].__subclasses__()`` or
+# ``getattr(__builtins__, "eval")``. This is a *defense-in-depth* check —
+# real isolation requires a subprocess+seccomp sandbox, which is tracked
+# separately; this scanner just makes the obvious escape patterns loud.
+BLOCKED_DUNDERS = frozenset({
+    "__class__", "__bases__", "__mro__", "__subclasses__",
+    "__globals__", "__builtins__", "__import__",
+    "__getattribute__", "__dict__", "__code__",
+})
+
+_DYNAMIC_ATTR_FUNCS = frozenset({"getattr", "setattr", "delattr"})
+
+
+@dataclass
+class ScanFinding:
+    rule_id: str
+    severity: str        # "critical" | "warning" | "info"
+    line: int
+    message: str
+    evidence: str
+
+
+@dataclass
+class ASTScanResult:
+    skill_id: str
+    status: str           # "clean" | "warning" | "critical"
+    findings: List[ScanFinding] = field(default_factory=list)
+    scanned_lines: int = 0
+    duration_ms: int = 0
+
+    @property
+    def has_critical(self) -> bool:
+        return any(f.severity == "critical" for f in self.findings)
+
+    @property
+    def has_warning(self) -> bool:
+        return any(f.severity == "warning" for f in self.findings)
+
+
+class ASTScanner:
+    """Python AST-based static analysis for skill source code.
+
+    Checks for:
+      - Direct calls to blocked builtins (exec, eval, etc.)  [BLT001]
+      - Imports of blocked modules                            [IMP001]
+      - base64.decode + exec/eval combinations               [OBF001]
+      - os.environ access to undeclared variables            [ENV001]
+      - Dunder access used to escape the builtins allowlist  [ESC001]
+      - getattr/setattr/delattr with dynamic/dunder targets  [ESC002]
+      - socket.connect to non-declared hosts                 [NET001]
+
+    Defense-in-depth only: a determined attacker can still compose escapes
+    this static scanner misses. Real isolation needs a subprocess + seccomp
+    sandbox, which is out of scope here.
+    """
+
+    def scan(self, source: str, skill_id: str) -> ASTScanResult:
+        """Scan Python source for security findings.
+
+        Args:
+            source:   Python source code string.
+            skill_id: Identifier used in the result.
+
+        Returns:
+            ASTScanResult with status and list of findings.
+        """
+        lines = source.splitlines()
+        findings: List[ScanFinding] = []
+        try:
+            tree = ast.parse(source)
+        except SyntaxError as exc:
+            return ASTScanResult(
+                skill_id=skill_id,
+                status="critical",
+                findings=[ScanFinding(
+                    rule_id="SYN001",
+                    severity="critical",
+                    line=exc.lineno or 0,
+                    message="Syntax error prevents AST analysis.",
+                    evidence=str(exc),
+                )],
+                scanned_lines=len(lines),
+            )
+
+        # Track imports to detect obfuscation combos
+        imported_modules: set[str] = set()
+
+        for node in ast.walk(tree):
+            # BLT001: blocked builtins
+            if isinstance(node, ast.Call):
+                func_name = self._call_name(node)
+                if func_name in BLOCKED_BUILTINS:
+                    findings.append(ScanFinding(
+                        rule_id="BLT001",
+                        severity="critical",
+                        line=node.lineno,
+                        message=f"Blocked builtin call: {func_name}()",
+                        evidence=ast.unparse(node)[:200],
+                    ))
+
+            # IMP001: blocked module imports
+            if isinstance(node, (ast.Import, ast.ImportFrom)):
+                mods = self._import_names(node)
+                for mod in mods:
+                    imported_modules.add(mod.split(".")[0])
+                    if any(mod == b or mod.startswith(b + ".") for b in BLOCKED_MODULES):
+                        findings.append(ScanFinding(
+                            rule_id="IMP001",
+                            severity="critical",
+                            line=node.lineno,
+                            message=f"Blocked module import: {mod}",
+                            evidence=ast.unparse(node)[:200],
+                        ))
+
+            # ENV001: os.environ access
+            if isinstance(node, ast.Attribute):
+                if (
+                    isinstance(node.value, ast.Name)
+                    and node.value.id == "os"
+                    and node.attr == "environ"
+                ):
+                    findings.append(ScanFinding(
+                        rule_id="ENV001",
+                        severity="warning",
+                        line=node.lineno,
+                        message="os.environ access detected; verify env vars are declared.",
+                        evidence=ast.unparse(node)[:200],
+                    ))
+
+                # ESC001: dunder access used to escape the builtins allowlist
+                if node.attr in BLOCKED_DUNDERS:
+                    findings.append(ScanFinding(
+                        rule_id="ESC001",
+                        severity="critical",
+                        line=node.lineno,
+                        message=f"Blocked dunder access: .{node.attr}",
+                        evidence=ast.unparse(node)[:200],
+                    ))
+
+            # ESC002: getattr/setattr/delattr with a dynamic or dunder target
+            if isinstance(node, ast.Call):
+                func_name = self._call_name(node)
+                if func_name in _DYNAMIC_ATTR_FUNCS and len(node.args) >= 2:
+                    second = node.args[1]
+                    flagged = False
+                    # getattr(x, "__class__") or similar constant dunder
+                    if isinstance(second, ast.Constant) and isinstance(second.value, str):
+                        if second.value in BLOCKED_DUNDERS:
+                            flagged = True
+                    # getattr(x, some_variable) — dynamic attribute name
+                    elif not isinstance(second, ast.Constant):
+                        flagged = True
+                    if flagged:
+                        findings.append(ScanFinding(
+                            rule_id="ESC002",
+                            severity="critical",
+                            line=node.lineno,
+                            message=f"{func_name}() with dynamic or dunder attribute",
+                            evidence=ast.unparse(node)[:200],
+                        ))
+
+        # OBF001: base64 + exec combo (check if both in imports or calls)
+        has_base64 = "base64" in imported_modules
+        has_exec_call = any(f.rule_id == "BLT001" and "exec" in f.message for f in findings)
+        if has_base64 and has_exec_call:
+            findings.append(ScanFinding(
+                rule_id="OBF001",
+                severity="critical",
+                line=0,
+                message="Potential obfuscation: base64 import combined with exec() call.",
+                evidence="base64 + exec combination detected.",
+            ))
+
+        has_critical = any(f.severity == "critical" for f in findings)
+        has_warning = any(f.severity == "warning" for f in findings)
+        status = "critical" if has_critical else ("warning" if has_warning else "clean")
+        return ASTScanResult(
+            skill_id=skill_id,
+            status=status,
+            findings=findings,
+            scanned_lines=len(lines),
+        )
+
+    @staticmethod
+    def _call_name(node: ast.Call) -> str:
+        if isinstance(node.func, ast.Name):
+            return node.func.id
+        if isinstance(node.func, ast.Attribute):
+            return node.func.attr
+        return ""
+
+    @staticmethod
+    def _import_names(node: ast.stmt) -> List[str]:
+        names: List[str] = []
+        if isinstance(node, ast.Import):
+            names = [alias.name for alias in node.names]
+        elif isinstance(node, ast.ImportFrom):
+            mod = node.module or ""
+            names = [f"{mod}.{alias.name}" for alias in node.names] + [mod]
+        return names

apsimo/skills_memory/__init__.py

@@ -0,0 +1,26 @@
+"""Compounding learning: reusable procedure memory (item 3).
+
+Distills a compact Skill (situation, steps, gotchas) from non-trivial
+successes -- success after a retry, or a novel diagnosis -- and retrieves the
+relevant ones into executor/planner prompts so the second encounter with a
+problem class starts from the first one's solution. Failures update a short
+per-domain strategy note (post-mortem memory).
+
+Named ``skills_memory`` to avoid clashing with the existing ``skills/``
+executor-skill registry (packaged executable skills). These are prompt-level
+procedure memories for the sidecar's own reasoning loops; they inform
+reasoning and never act, so retrieval is safe to run live
+(COLONY_SKILLS_ENABLED, default true). Distillation costs one LLM call per
+qualifying completion and starts in shadow (COLONY_SKILLS_DISTILL).
+"""
+
+from apsimo.skills_memory.models import Skill, signature_overlap, situation_signature
+from apsimo.skills_memory.store import SkillStore, skills_enabled, skills_distill_mode
+from apsimo.skills_memory.distill import should_distill, distill_from_completion
+from apsimo.skills_memory.retrieve import relevant_skills, format_block
+
+__all__ = [
+    "Skill", "SkillStore", "signature_overlap", "situation_signature",
+    "should_distill", "distill_from_completion", "relevant_skills",
+    "format_block", "skills_enabled", "skills_distill_mode",
+]

apsimo/skills_memory/distill.py

@@ -0,0 +1,159 @@
+"""Skill distillation: one bounded LLM pass on qualifying completions.
+
+Trigger discipline keeps the LLM cost modest and the library honest:
+only success AFTER at least one retry, or a completion whose result carries a
+resolution not already covered by an existing skill, qualifies. The LLM
+proposes {title, situation, steps, gotchas} as STRICT JSON; code validates,
+dedups by situation-signature overlap (>0.8 bumps the existing skill instead
+of storing a near-duplicate), and enforces the library cap.
+
+Modes (COLONY_SKILLS_DISTILL): off | shadow (log the would-be skill, store
+nothing) | live. Default shadow.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from typing import Any, List, Optional
+
+from apsimo.skills_memory.models import (
+    Skill, signature_overlap, situation_signature,
+)
+from apsimo.skills_memory.store import SkillStore, skills_distill_mode, skills_max
+
+logger = logging.getLogger(__name__)
+
+# Result text that indicates a diagnosis/resolution worth remembering.
+_RESOLUTION_RE = re.compile(
+    r"\b(?:root cause|fixed by|resolved by|the fix|turned out|workaround|"
+    r"solution was|caused by|diagnos)\w*\b", re.IGNORECASE)
+
+_MAX_STEPS = 10
+_MAX_GOTCHAS = 5
+
+_SYSTEM_PROMPT = """\
+You distill reusable procedures from completed work. Given a task and how it
+was completed, extract ONE compact, generic procedure another agent could
+follow when a similar situation recurs.
+
+Respond with ONLY a JSON object (no prose, no markdown fences):
+{"title": str (<80 chars, imperative), "situation": str (when this applies,
+<200 chars), "steps": [str, ...] (2-8 concrete steps), "gotchas": [str, ...]
+(0-4 pitfalls, may be empty)}.
+Generalize: replace deployment-specific names (hosts, people, repos, ids)
+with role placeholders like <host>, <repo>, <person> so the procedure
+transfers to similar situations. Every step must be grounded in what
+actually happened in the work log; never invent steps.
+If the work contains no reusable procedure, respond with exactly: null"""
+
+
+def should_distill(attempt_count: int, result_text: str,
+                   store: Optional[SkillStore]) -> bool:
+    """Trigger conditions: retry-success, or a novel diagnosis in the result."""
+    if attempt_count and int(attempt_count) >= 1:
+        return True
+    text = (result_text or "").strip()
+    if not text or not _RESOLUTION_RE.search(text):
+        return False
+    # Novel: the resolution's signature is not already covered by a skill.
+    if store is not None:
+        sig = situation_signature(text[:400])
+        for s in store.list(limit=1000):
+            if signature_overlap(sig, s.situation_signature) > 0.5:
+                return False
+    return True
+
+
+def _parse_skill_json(content: str) -> Optional[dict]:
+    text = (content or "").strip()
+    if "```" in text:
+        m = re.search(r"```(?:json)?\s*(.*?)```", text, re.DOTALL)
+        if m:
+            text = m.group(1).strip()
+    if text.lower() in ("null", "none", ""):
+        return None
+    if not text.startswith("{"):
+        m = re.search(r"\{.*\}", text, re.DOTALL)
+        if not m:
+            return None
+        text = m.group(0)
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError:
+        logger.debug("skill distill output was not valid JSON; dropping")
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _validate(data: dict, domain: str, source_ref: str) -> Optional[Skill]:
+    title = str(data.get("title", "")).strip()[:120]
+    situation = str(data.get("situation", "")).strip()[:400]
+    steps = [str(s).strip()[:300] for s in (data.get("steps") or [])
+             if str(s).strip()][:_MAX_STEPS]
+    gotchas = [str(g).strip()[:300] for g in (data.get("gotchas") or [])
+               if str(g).strip()][:_MAX_GOTCHAS]
+    if not title or not situation or not steps:
+        return None
+    return Skill(title=title, situation=situation, steps=steps,
+                 gotchas=gotchas, domain=(domain or "").lower(),
+                 source_ref=source_ref)
+
+
+async def distill_from_completion(
+    router: Any,
+    store: Optional[SkillStore],
+    *,
+    domain: str,
+    task_text: str,
+    result_text: str,
+    source_ref: str = "",
+    mode: Optional[str] = None,
+) -> Optional[Skill]:
+    """One reasoning pass -> validated, deduped Skill (or None).
+
+    Returns the stored (or shadow-logged) Skill. Dedup: an existing skill with
+    >0.8 signature overlap gets its use count bumped instead.
+    """
+    mode = mode or skills_distill_mode()
+    if mode == "off" or router is None:
+        return None
+    prompt = (f"TASK ({domain}):\n{(task_text or '')[:1500]}\n\n"
+              f"HOW IT WAS COMPLETED:\n{(result_text or '')[:2500]}")
+    try:
+        response = await router.complete(
+            [{"role": "system", "content": _SYSTEM_PROMPT},
+             {"role": "user", "content": prompt}],
+            context={"task": "skill_distillation"})
+        content = getattr(response, "content", "") or ""
+    except Exception as exc:
+        logger.debug("skill distillation LLM call failed: %s", exc)
+        return None
+
+    data = _parse_skill_json(content)
+    if not data:
+        return None
+    skill = _validate(data, domain, source_ref)
+    if skill is None:
+        return None
+
+    if store is not None:
+        existing = store.find_similar(skill.situation_signature, threshold=0.8)
+        if existing is not None:
+            store.bump_use(existing.id)
+            logger.info("skills_memory: near-duplicate of %s -- bumped use "
+                        "instead of storing %r", existing.id, skill.title)
+            return existing
+
+    if mode == "shadow":
+        logger.info("SHADOW-SKILL distilled (not stored): %s",
+                    json.dumps(skill.to_row(), default=str)[:600])
+        return skill
+
+    if store is not None:
+        store.add(skill)
+        store.evict_to_cap(skills_max())
+        logger.info("skills_memory: stored skill %s %r (domain=%s)",
+                    skill.id, skill.title, skill.domain)
+    return skill

apsimo/skills_memory/models.py

@@ -0,0 +1,85 @@
+"""Skill data model + situation-signature matching."""
+
+from __future__ import annotations
+
+import json
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from apsimo.directives.models import normalize_terms
+
+
+def situation_signature(text: str) -> str:
+    """Normalized, order-stable term signature for a situation description."""
+    return " ".join(sorted(set(normalize_terms(text))))
+
+
+def signature_overlap(sig_a: str, sig_b: str) -> float:
+    """Jaccard overlap between two signatures (0..1)."""
+    a, b = set((sig_a or "").split()), set((sig_b or "").split())
+    if not a or not b:
+        return 0.0
+    return len(a & b) / len(a | b)
+
+
+@dataclass
+class Skill:
+    title: str
+    situation: str = ""                 # when does this apply
+    steps: List[str] = field(default_factory=list)
+    gotchas: List[str] = field(default_factory=list)
+    domain: str = ""                    # initiative type | project | directed
+    source_ref: str = ""                # initiative/project/job id it came from
+    situation_signature: str = ""       # derived from situation when empty
+    uses: int = 0
+    wins: int = 0
+    losses: int = 0
+    confidence: float = 0.6
+    id: str = field(default_factory=lambda: f"skl-{uuid.uuid4().hex[:12]}")
+    created_at: float = field(default_factory=time.time)
+    last_used_at: Optional[float] = None
+
+    def __post_init__(self) -> None:
+        if not self.situation_signature:
+            self.situation_signature = situation_signature(
+                f"{self.title} {self.situation}")
+
+    def score(self, now: Optional[float] = None) -> float:
+        """Eviction score: confidence + track record - staleness."""
+        now = now or time.time()
+        age_days = max(0.0, (now - (self.last_used_at or self.created_at)) / 86400.0)
+        return self.confidence + 0.2 * (self.wins - self.losses) - age_days / 180.0
+
+    def to_row(self) -> Dict[str, Any]:
+        return {
+            "id": self.id, "title": self.title, "situation": self.situation,
+            "situation_signature": self.situation_signature,
+            "steps": json.dumps(self.steps), "gotchas": json.dumps(self.gotchas),
+            "domain": self.domain, "source_ref": self.source_ref,
+            "uses": self.uses, "wins": self.wins, "losses": self.losses,
+            "confidence": self.confidence, "created_at": self.created_at,
+            "last_used_at": self.last_used_at,
+        }
+
+    @classmethod
+    def from_row(cls, r: Dict[str, Any]) -> "Skill":
+        def _j(key):
+            try:
+                v = json.loads(r.get(key) or "[]")
+                return [str(x) for x in v] if isinstance(v, list) else []
+            except Exception:
+                return []
+        return cls(
+            id=r["id"], title=r.get("title", "") or "",
+            situation=r.get("situation", "") or "",
+            situation_signature=r.get("situation_signature", "") or "",
+            steps=_j("steps"), gotchas=_j("gotchas"),
+            domain=r.get("domain", "") or "", source_ref=r.get("source_ref", "") or "",
+            uses=int(r.get("uses") or 0), wins=int(r.get("wins") or 0),
+            losses=int(r.get("losses") or 0),
+            confidence=float(r.get("confidence", 0.6) or 0.6),
+            created_at=float(r.get("created_at") or time.time()),
+            last_used_at=(float(r["last_used_at"]) if r.get("last_used_at") else None),
+        )

apsimo/skills_memory/retrieve.py

@@ -0,0 +1,62 @@
+"""Skill retrieval: situation -> the k most relevant procedures, as a compact
+prompt block. Pure read; keyword-signature scoring (embedding optional later)."""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from apsimo.skills_memory.models import (
+    Skill, signature_overlap, situation_signature,
+)
+from apsimo.skills_memory.store import SkillStore
+
+_MIN_OVERLAP = 0.08
+
+
+def relevant_skills(store: Optional[SkillStore], situation: str,
+                    k: int = 3, domain: Optional[str] = None) -> List[Skill]:
+    """Top-k skills by signature overlap with the situation (domain-boosted)."""
+    if store is None or not (situation or "").strip():
+        return []
+    sig = situation_signature(situation)
+    scored = []
+    for s in store.list(limit=100000):
+        ov = signature_overlap(sig, s.situation_signature)
+        if domain and s.domain == (domain or "").lower():
+            ov += 0.05
+        # Track-record weighting: skills that historically informed winning
+        # runs rank up, losers rank down. Laplace prior keeps a fresh skill
+        # neutral (factor 1.0); the executor's outcome attribution feeds
+        # wins/losses, so use changes future retrieval.
+        wins = int(getattr(s, "wins", 0) or 0)
+        losses = int(getattr(s, "losses", 0) or 0)
+        win_rate = (wins + 1.0) / (wins + losses + 2.0)
+        ov *= 0.75 + 0.5 * win_rate
+        if ov >= _MIN_OVERLAP:
+            scored.append((ov, s))
+    scored.sort(key=lambda t: t[0], reverse=True)
+    top = [s for _, s in scored[:k]]
+    for s in top:
+        try:
+            store.bump_use(s.id)
+        except Exception:
+            pass
+    return top
+
+
+def format_block(skills: List[Skill], strategy_note: str = "") -> str:
+    """Render skills (+ optional per-domain strategy note) for a system prompt.
+    Empty string when there is nothing to say."""
+    lines: List[str] = []
+    if skills:
+        lines.append("## Relevant past procedures (learned from your own prior work)")
+        for s in skills:
+            lines.append(f"- {s.title} -- applies when: {s.situation}")
+            for i, step in enumerate(s.steps, 1):
+                lines.append(f"    {i}. {step}")
+            for g in s.gotchas:
+                lines.append(f"    ! gotcha: {g}")
+    if (strategy_note or "").strip():
+        lines.append("## Lessons from past failures in this domain")
+        lines.append(strategy_note.strip())
+    return "\n".join(lines)