power-loop 0.2.0__py3-none-any.whl

power_loop/runtime/skills.py

@@ -0,0 +1,201 @@
+"""Skill loading from ``SKILL.md`` files.
+
+Skills are Markdown files with YAML frontmatter. Each skill lives in its own
+directory under ``skills_dir``::
+
+    skills_dir/
+    ├── python-expert/
+    │   └── SKILL.md      # name: python-expert, description: ...
+    └── security-reviewer/
+        └── SKILL.md
+
+The library ships with a :class:`SkillLoader` that parses these files and
+provides ``get_descriptions()`` (for system prompts) and ``get_content()``
+(for detailed instructions). A ``load_skill`` tool can be registered in
+:class:`ToolRegistry` so the LLM can dynamically fetch skill content.
+"""
+
+from __future__ import annotations
+
+import re
+from importlib import import_module
+from importlib.util import find_spec
+from pathlib import Path
+from typing import Any
+
+from power_loop.contracts.tools import ToolDefinition
+from power_loop.runtime.env import AGENT_DIR, WORKSPACE_DIR
+from power_loop.runtime.env import SKILLS_DIR as ENV_SKILLS_DIR
+
+_yaml = import_module("yaml") if find_spec("yaml") else None
+
+LOAD_SKILL_DEFINITION = ToolDefinition(
+    name="load_skill",
+    description=(
+        "Load the full content of a skill by name. "
+        "Use this when you need detailed instructions for a specific domain. "
+        "Param: name (string) — the skill name (e.g. 'python-expert')."
+    ),
+    input_schema={
+        "type": "object",
+        "properties": {"name": {"type": "string", "description": "Skill name to load"}},
+        "required": ["name"],
+    },
+    required_params=("name",),
+)
+
+
+def _resolve_skills_dir(explicit: str | Path | None) -> Path:
+    """Resolve the skills directory from config, env, or default."""
+    if explicit is not None:
+        path = Path(explicit).expanduser()
+        if not path.is_absolute():
+            path = (AGENT_DIR / path).resolve()
+        else:
+            path = path.resolve()
+        if path.exists() and path.is_dir():
+            return path
+    return ENV_SKILLS_DIR
+
+
+class SkillLoader:
+    """Loads and caches ``SKILL.md`` files from a directory tree.
+
+    Args:
+        skills_dir: Path to the directory containing skill subdirectories.
+            If ``None``, uses the env-var / default resolution chain.
+
+    The loader scans for ``*/SKILL.md`` files and parses their YAML
+    frontmatter. Each skill's ``name`` comes from its parent directory name.
+    """
+
+    def __init__(self, skills_dir: str | Path | None = None):
+        self.skills_dir: Path = _resolve_skills_dir(skills_dir)
+        self.skills: dict[str, dict[str, Any]] = {}
+        self._load_all()
+
+    def reload(self) -> None:
+        """Rescan the skills directory. Call after adding/removing skills."""
+        self.skills.clear()
+        self._load_all()
+
+    # ── Internal ────────────────────────────────────────────────────────
+
+    def _load_all(self) -> None:
+        if not self.skills_dir.exists():
+            return
+        for f in sorted(self.skills_dir.glob("*/SKILL.md")):
+            name = f.parent.name
+            text = f.read_text(encoding="utf-8")
+            meta, body = self._parse_frontmatter(text)
+            self.skills[name] = {"meta": meta, "body": body, "path": str(f.resolve())}
+
+    @staticmethod
+    def _parse_frontmatter(text: str) -> tuple[dict[str, Any], str]:
+        match = re.match(r"^---\s*\n(.*?)\n---\s*\n(.*)", text, re.DOTALL)
+        if not match:
+            return {}, text.strip()
+        body = match.group(2).strip()
+        if _yaml is None:
+            return {}, body
+        try:
+            meta = _yaml.safe_load(match.group(1))
+            if not isinstance(meta, dict):
+                meta = {}
+        except Exception:
+            meta = {}
+        return meta, body
+
+    # ── Public API ──────────────────────────────────────────────────────
+
+    @property
+    def names(self) -> list[str]:
+        """Sorted list of available skill names."""
+        return sorted(self.skills.keys())
+
+    def get_descriptions(self) -> str:
+        """One-line-per-skill summary suitable for system prompts."""
+        if not self.skills:
+            return "(no skills available)"
+        lines = ["Available skills:"]
+        for name in sorted(self.skills):
+            s = self.skills[name]
+            desc = s["meta"].get("description", "No description")
+            lines.append(f"  - {name}: {desc}")
+        return "\n".join(lines)
+
+    def get_content(self, name: str) -> str:
+        """Full instructions for a skill, including execution context."""
+        skill = self.skills.get(name)
+        if not skill:
+            available = ", ".join(sorted(self.skills))
+            return f"Error: Unknown skill '{name}'. Available: {available}"
+        skill_path = Path(skill["path"]).resolve()
+        skill_root = skill_path.parent
+        return (
+            f'<skill name="{name}" path="{skill["path"]}">\n'
+            f"Source: {skill['path']}\n\n"
+            "[Execution Context]\n"
+            f"- Workspace (user project): {WORKSPACE_DIR}\n"
+            f"- Agent home: {AGENT_DIR}\n"
+            f"- Skill root: {skill_root}\n"
+            "- Rules:\n"
+            f"  1) Run skill-relative commands from skill root: {skill_root}\n"
+            f"  2) Prefer absolute paths when applicable.\n"
+            "  3) Output files go to workspace.\n"
+            "  4) Do not search outside workspace/skill root unless requested.\n\n"
+            f"{skill['body']}\n"
+            "</skill>"
+        )
+
+    def build_system_prompt_section(self) -> str:
+        """A section to append to ``AgentLoopConfig.system_prompt``.
+
+        Includes skill descriptions in a compact format the LLM can parse.
+        """
+        if not self.skills:
+            return ""
+        parts = ["## Available Skills"]
+        parts.append(
+            "You have a `load_skill` tool. Call `load_skill(name=\"...\")` "
+            "to get detailed instructions for any skill below.\n"
+        )
+        parts.append(self.get_descriptions())
+        return "\n".join(parts)
+
+    # ── Tool handler ────────────────────────────────────────────────────
+
+    def handle_load_skill(self, name: str) -> str:
+        """Handler for the ``load_skill`` tool. Returns the skill's full content."""
+        return self.get_content(name)
+
+
+# Module-level singleton for backward compatibility.
+_default_loader: SkillLoader | None = None
+
+
+def get_default_loader() -> SkillLoader:
+    """Return the module-level :class:`SkillLoader` singleton."""
+    global _default_loader
+    if _default_loader is None:
+        _default_loader = SkillLoader()
+    return _default_loader
+
+
+def register_skill_tools(registry, *, skills_dir: str | Path | None = None) -> SkillLoader:
+    """Register the ``load_skill`` tool in the given registry.
+
+    Returns the :class:`SkillLoader` instance so callers can inspect or
+    inject the skill descriptions into the system prompt.
+    """
+    loader = SkillLoader(skills_dir)
+    registry.register(LOAD_SKILL_DEFINITION, loader.handle_load_skill)
+    return loader
+
+
+__all__ = [
+    "LOAD_SKILL_DEFINITION",
+    "SkillLoader",
+    "get_default_loader",
+    "register_skill_tools",
+]

power_loop/runtime/spec.py

@@ -0,0 +1,233 @@
+"""Declarative subagent spec (M1.8).
+
+The parent agent emits an :class:`AgentSpec` (as JSON or dict) describing
+*what kind of* subagent to run, and :func:`run_agent_spec` materializes it as
+a child :class:`StatefulAgentLoop` session.
+
+This is the in-process complement of the imperative :mod:`spawn_agent` tool:
+
+* ``spawn_agent`` — a tool the LLM calls in turn-form ("delegate this task").
+* ``run_agent`` (meta-tool) — accepts a full :class:`AgentSpec` JSON for
+  cases where the parent wants explicit control over the child's tool
+  whitelist / model / max_rounds / system prompt.
+
+Both paths reuse this module's :func:`run_agent_spec` so depth-guard,
+parent-linking, lifecycle cleanup and tool-whitelist filtering live in one
+place.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field, fields
+from typing import Any
+
+from power_loop.agent.types import AgentLoopConfig
+from power_loop.contracts.errors import SpecValidationError
+from power_loop.runtime.session_store import MAX_SPAWN_DEPTH, SubagentLifecycle
+from power_loop.tools.registry import ToolRegistry
+
+__all__ = [
+    "AgentSpec",
+    "AgentSpecError",
+    "filtered_registry",
+    "run_agent_spec",
+]
+
+
+class AgentSpecError(SpecValidationError):
+    """Raised when an :class:`AgentSpec` payload fails strict validation.
+
+    Inherits from :class:`~power_loop.contracts.errors.SpecValidationError`
+    so ``except PowerLoopError`` catches it alongside all other library errors.
+    """
+    # Keep ValueError-compatible interface for callers that already do
+    # ``except ValueError`` or ``except AgentSpecError``.
+    pass
+
+
+@dataclass(frozen=True)
+class AgentSpec:
+    """Strict-schema description of a one-shot subagent run.
+
+    All fields are explicit; unknown JSON keys are rejected so a hallucinated
+    payload from the parent LLM surfaces early.
+    """
+
+    name: str
+    system_prompt: str
+    tools: list[str] | None = None      # whitelist; None = inherit all from parent
+    max_rounds: int = 8
+    max_tokens: int = 4000
+    temperature: float = 0.0
+    model: str | None = None
+    lifecycle: str = SubagentLifecycle.EPHEMERAL.value
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    # ── validation ────────────────────────────────────────────────────────
+
+    def __post_init__(self) -> None:
+        if not self.name or not isinstance(self.name, str):
+            raise AgentSpecError("AgentSpec.name must be a non-empty string")
+        if not self.system_prompt or not isinstance(self.system_prompt, str):
+            raise AgentSpecError("AgentSpec.system_prompt must be a non-empty string")
+        if self.tools is not None:
+            if not isinstance(self.tools, list) or not all(isinstance(x, str) for x in self.tools):
+                raise AgentSpecError("AgentSpec.tools must be a list[str] or None")
+        if not 1 <= int(self.max_rounds) <= 50:
+            raise AgentSpecError("AgentSpec.max_rounds must be in [1, 50]")
+        try:
+            SubagentLifecycle(self.lifecycle)
+        except ValueError as exc:
+            raise AgentSpecError(f"unknown lifecycle: {self.lifecycle}") from exc
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> AgentSpec:
+        allowed = {f.name for f in fields(cls)}
+        unknown = set(data) - allowed
+        if unknown:
+            raise AgentSpecError(f"unknown AgentSpec field(s): {sorted(unknown)}")
+        return cls(**{k: v for k, v in data.items() if k in allowed})
+
+    @classmethod
+    def from_json(cls, payload: str | dict[str, Any]) -> AgentSpec:
+        if isinstance(payload, str):
+            try:
+                data = json.loads(payload)
+            except json.JSONDecodeError as exc:
+                raise AgentSpecError(f"AgentSpec JSON parse error: {exc}") from exc
+        else:
+            data = dict(payload)
+        if not isinstance(data, dict):
+            raise AgentSpecError("AgentSpec payload must decode to an object")
+        return cls.from_dict(data)
+
+
+# ── helpers ──────────────────────────────────────────────────────────────
+
+
+def filtered_registry(
+    parent_registry: ToolRegistry | None, whitelist: list[str] | None
+) -> ToolRegistry | None:
+    """Return a registry containing only the whitelisted tools from ``parent``.
+
+    * ``parent_registry=None`` → ``None``
+    * ``whitelist=None`` → return the parent registry as-is (full inherit)
+    * Names missing from the parent registry are silently skipped (subagent
+      simply doesn't see them).
+    """
+    if parent_registry is None:
+        return None
+    if whitelist is None:
+        return parent_registry
+    sub = ToolRegistry()
+    for name in whitelist:
+        existing = parent_registry.get(name)
+        if existing is None:
+            continue
+        sub.register(existing.definition, existing.handler, overwrite=True)
+    return sub
+
+
+async def run_agent_spec(
+    spec: AgentSpec | dict[str, Any] | str,
+    user_input: str,
+    *,
+    parent_loop: Any,
+    spawn_tool_call_id: str | None = None,
+) -> dict[str, Any]:
+    """Materialize ``spec`` as a child session under ``parent_loop`` and run it.
+
+    Returns a dict with ``final_text``, ``status``, ``rounds``, ``session_id``,
+    ``depth`` — easy for the parent LLM to consume as a tool result.
+
+    Lifecycle:
+      * ``EPHEMERAL`` (default) → child session is deleted on success;
+        preserved on non-completed status (``hit_round_limit`` / ``cancelled``)
+        so the parent can debug.
+      * ``LINKED`` → child kept; cascade-deleted when parent is closed.
+      * ``DETACHED`` → child kept, lives independently.
+    """
+    if not isinstance(spec, AgentSpec):
+        spec = AgentSpec.from_json(spec)
+
+    parent_sid = None
+    # parent_loop must be a StatefulAgentLoop; we accept Any to avoid a cycle.
+    from power_loop.core.agent_context import get_session_id
+    parent_sid = get_session_id()
+
+    # Pre-check depth so we don't even create the session row if it'll bounce.
+    if parent_sid is not None:
+        parent_row = parent_loop.store.get_session(parent_sid)
+        if parent_row is not None and parent_row.spawn_depth + 1 > MAX_SPAWN_DEPTH:
+            return {
+                "session_id": None,
+                "status": "rejected",
+                "final_text": (
+                    f"spawn rejected — depth {parent_row.spawn_depth + 1} "
+                    f"exceeds max {MAX_SPAWN_DEPTH}"
+                ),
+                "rounds": 0,
+                "depth": parent_row.spawn_depth + 1,
+            }
+
+    child_config = AgentLoopConfig(
+        system_prompt=spec.system_prompt,
+        max_rounds=int(spec.max_rounds),
+        max_tokens=int(spec.max_tokens),
+        temperature=float(spec.temperature),
+    )
+
+    child_sid = parent_loop.store.create_session(
+        system_prompt=spec.system_prompt,
+        config={
+            "spec_name": spec.name,
+            "max_rounds": child_config.max_rounds,
+            "max_tokens": child_config.max_tokens,
+            "temperature": child_config.temperature,
+            "model": spec.model,
+        },
+        parent_session_id=parent_sid,
+        spawn_tool_call_id=spawn_tool_call_id,
+        lifecycle=SubagentLifecycle(spec.lifecycle),
+        metadata=dict(spec.metadata),
+    )
+
+    sub_registry = filtered_registry(parent_loop.tool_registry, spec.tools)
+
+    # Build a sibling loop sharing the same store + registry-subset.
+    from power_loop.agent.stateful_loop import StatefulAgentLoop
+
+    child_loop = StatefulAgentLoop(
+        llm=parent_loop.llm,
+        store=parent_loop.store,
+        config=child_config,
+        tool_registry=sub_registry,
+        hooks=parent_loop._runner.hooks,
+        event_bus=parent_loop._runner.event_bus,
+    )
+    result = await child_loop.send(user_input, session_id=child_sid)
+
+    # Lifecycle cleanup.
+    if spec.lifecycle == SubagentLifecycle.EPHEMERAL.value:
+        if result.status == "completed":
+            parent_loop.store.close_session(child_sid, cascade=True)
+            returned_sid: str | None = None
+        else:
+            # Preserve for debugging.
+            returned_sid = child_sid
+    else:
+        returned_sid = child_sid
+
+    child_row = parent_loop.store.get_session(child_sid)
+    depth = child_row.spawn_depth if child_row is not None else (
+        (parent_loop.store.get_session(parent_sid).spawn_depth + 1) if parent_sid else 1
+    )
+
+    return {
+        "session_id": returned_sid,
+        "status": result.status,
+        "final_text": result.final_text,
+        "rounds": result.rounds,
+        "depth": depth,
+    }

power_loop/runtime/structured.py

@@ -0,0 +1,225 @@
+"""Structured output helpers (M1.3).
+
+Two things, kept deliberately small:
+
+1. :class:`StructuredOutputSpec` —— declarative bundle of (name, JSON
+   schema, strict-mode) that knows how to render itself into the
+   OpenAI-compatible ``response_format`` dict the provider expects.
+2. :func:`parse_structured` —— extracts a JSON object from any LLM
+   response text, repairs common defects (markdown fences, trailing
+   commas, single quotes), and optionally validates against a minimal
+   subset of JSON Schema (``type=="object"`` + ``required`` keys).
+
+We do **not** depend on jsonschema or pydantic for parsing. The schema
+field is forwarded to the provider as-is for **server-side** validation
+(strict mode); local parsing only enforces "shape is an object and
+required keys are present", which is enough to catch the wedge cases
+that bite real Agents: the model wrote prose instead of JSON, or omitted
+a critical field.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from llm_client.interface import LLMResponse
+from power_loop.contracts.errors import PowerLoopError
+
+
+class StructuredOutputError(PowerLoopError):
+    """Raised when ``parse_structured`` cannot produce a valid object.
+
+    ``raw_text`` is the original LLM output (truncated); ``reason``
+    explains which check failed: ``no_json`` / ``invalid_json`` /
+    ``not_object`` / ``missing_required:<field>`` / ``wrong_type:<field>``.
+    """
+
+    def __init__(self, *, reason: str, raw_text: str, detail: str = "") -> None:
+        self.reason = reason
+        self.raw_text = raw_text[:1000]
+        self.detail = detail
+        msg = f"structured output rejected ({reason})"
+        if detail:
+            msg += f": {detail}"
+        super().__init__(msg)
+
+
+@dataclass
+class StructuredOutputSpec:
+    """Declarative spec for ``LLMRequest.response_format``.
+
+    The OpenAI ``json_schema`` mode requires a ``name`` and a ``schema``.
+    ``strict=True`` is the safer default (most providers will refuse
+    extra/missing keys server-side); set to ``False`` for providers that
+    don't yet support strict mode.
+    """
+
+    name: str
+    schema: dict[str, Any]
+    strict: bool = True
+    description: str | None = None
+    examples: list[dict[str, Any]] = field(default_factory=list)
+
+    def to_openai_response_format(self) -> dict[str, Any]:
+        """Render the ``response_format`` payload OpenAI-compatible APIs accept."""
+        js: dict[str, Any] = {"name": self.name, "schema": self.schema}
+        if self.strict:
+            js["strict"] = True
+        if self.description:
+            js["description"] = self.description
+        return {"type": "json_schema", "json_schema": js}
+
+
+# ── JSON repair ─────────────────────────────────────────────────────────
+
+
+_FENCE_RE = re.compile(r"^\s*```(?:json|JSON)?\s*\n?|\n?```\s*$", re.MULTILINE)
+
+
+def _strip_markdown_fences(text: str) -> str:
+    """Drop leading/trailing ```json / ``` fences if present."""
+    return _FENCE_RE.sub("", text).strip()
+
+
+def _extract_first_json_object(text: str) -> str | None:
+    """Find the first balanced ``{...}`` block. Skips string contents.
+
+    Returns the substring or ``None`` if no balanced object exists.
+    """
+    depth = 0
+    start = -1
+    in_str = False
+    esc = False
+    for i, ch in enumerate(text):
+        if in_str:
+            if esc:
+                esc = False
+            elif ch == "\\":
+                esc = True
+            elif ch == '"':
+                in_str = False
+            continue
+        if ch == '"':
+            in_str = True
+            continue
+        if ch == "{":
+            if depth == 0:
+                start = i
+            depth += 1
+        elif ch == "}":
+            depth -= 1
+            if depth == 0 and start >= 0:
+                return text[start : i + 1]
+    return None
+
+
+def _try_repair_json(blob: str) -> str:
+    """Apply cheap, reversible fixes that recover from typical LLM JSON noise.
+
+    Order matters: fence strip → trailing-comma → single→double quotes
+    (only when an attempt to ``json.loads`` already failed)."""
+    # Trailing commas before } or ]
+    return re.sub(r",(\s*[}\]])", r"\1", blob)
+
+
+def parse_structured(
+    output: LLMResponse | str,
+    *,
+    schema: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Extract a dict from an LLM response, repairing common JSON defects.
+
+    Steps:
+
+    1. Pull text from ``LLMResponse`` (``raw_text`` / ``content_text``)
+       or use the string directly.
+    2. Strip markdown fences.
+    3. Try ``json.loads`` directly; on failure, find the first balanced
+       ``{...}`` and retry; on failure, apply trailing-comma repair and
+       retry once more.
+    4. If a ``schema`` is supplied, check ``type=="object"`` shape and
+       all ``required`` keys are present. Mismatches raise
+       :class:`StructuredOutputError` with a precise ``reason``.
+
+    Args:
+        output: An ``LLMResponse`` or the raw text string.
+        schema: Optional JSON-Schema-flavoured dict. Only ``type`` and
+            ``required`` (top-level) are enforced locally; the full
+            schema is what the provider validates server-side when used
+            via :class:`StructuredOutputSpec`.
+
+    Returns:
+        The parsed dict.
+
+    Raises:
+        StructuredOutputError: with ``reason`` in ``{"no_json",
+        "invalid_json", "not_object", "missing_required:<field>"}``.
+    """
+    text = output if isinstance(output, str) else (
+        getattr(output, "raw_text", "") or getattr(output, "content_text", "") or ""
+    )
+    text = text or ""
+    cleaned = _strip_markdown_fences(text)
+
+    parsed: Any = None
+    for attempt in ("direct", "extract", "repair"):
+        candidate = cleaned
+        if attempt == "extract":
+            extracted = _extract_first_json_object(cleaned)
+            if extracted is None:
+                continue
+            candidate = extracted
+        elif attempt == "repair":
+            extracted = _extract_first_json_object(cleaned) or cleaned
+            candidate = _try_repair_json(extracted)
+        try:
+            parsed = json.loads(candidate)
+            break
+        except Exception:
+            continue
+    else:
+        # Distinguish "no object at all" from "object but malformed".
+        reason = "no_json" if _extract_first_json_object(cleaned) is None else "invalid_json"
+        raise StructuredOutputError(reason=reason, raw_text=text)
+
+    if not isinstance(parsed, Mapping):
+        raise StructuredOutputError(reason="not_object", raw_text=text,
+                                    detail=f"got {type(parsed).__name__}")
+    parsed = dict(parsed)
+
+    if schema is not None:
+        _check_top_level_schema(parsed, schema, raw_text=text)
+    return parsed
+
+
+def _check_top_level_schema(obj: dict[str, Any], schema: dict[str, Any], *, raw_text: str) -> None:
+    """Minimal local validation: top-level type=object + required keys present.
+
+    Anything deeper (per-field type checking, enum, regex, nested
+    schemas) is intentionally delegated to the provider's strict-mode
+    server-side validation. Doing it here would duplicate a real
+    json-schema implementation and silently disagree with the provider
+    in edge cases.
+    """
+    expected_type = schema.get("type")
+    if expected_type not in (None, "object"):
+        raise StructuredOutputError(
+            reason="not_object", raw_text=raw_text,
+            detail=f"schema requires type={expected_type!r}",
+        )
+    for field_name in schema.get("required") or []:
+        if field_name not in obj:
+            raise StructuredOutputError(
+                reason=f"missing_required:{field_name}", raw_text=raw_text,
+            )
+
+
+__all__ = [
+    "StructuredOutputError",
+    "StructuredOutputSpec",
+    "parse_structured",
+]