agentkernel-cli 0.1.0__py3-none-any.whl

agentkernel/skills.py

@@ -0,0 +1,268 @@
+"""Skills, Anthropic-style (design §13, Phase 4).
+
+A skill is a reusable bundle of instructions the model can apply. This follows
+the Anthropic Agent Skills shape: a ``SKILL.md`` with YAML frontmatter
+(``name`` + ``description``) and a markdown body, optionally alongside bundled
+scripts/resources in the same folder.
+
+Disclosure is **progressive** (hybrid): only each skill's name + description
+sits in the cacheable prefix (a lightweight catalog, always present), and the
+model loads a skill's full body + file listing on demand via the ``use_skill``
+tool. A skill may additionally be *pinned* (``active``) so its full body is
+injected into the prefix up front.
+
+Discovery accepts three layouts so existing skills keep working:
+  * ``<dir>/<skill>/SKILL.md`` — Anthropic-style folder (bundled files allowed)
+  * ``<dir>/<skill>.md`` — a loose markdown file (optional ``---`` frontmatter)
+  * ``<dir>/<skill>.toml`` — frontmatter-only (``name`` + ``system_prompt``)
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+
+@dataclass(frozen=True)
+class Skill:
+    """A named skill: a description (for disclosure) + a body (the instructions)."""
+
+    name: str
+    description: str
+    body: str
+    source: Path | None = None
+    resources: tuple[str, ...] = ()  # bundled file paths, relative to cwd
+
+    @property
+    def system_prompt(self) -> str:  # back-compat alias
+        return self.body
+
+
+@runtime_checkable
+class ContextSource(Protocol):
+    """Anything that contributes extra system-prompt text per run."""
+
+    def system_additions(self) -> list[str]: ...
+
+
+def _split_frontmatter(text: str) -> tuple[dict[str, object], str]:
+    """Split a ``---`` delimited frontmatter block from the body.
+
+    Returns ``(metadata, body)``. The frontmatter is parsed as a small YAML
+    subset (flat ``key: value`` plus ``- item`` lists) — enough for SKILL.md,
+    without taking a YAML dependency.
+    """
+    if not text.startswith("---"):
+        return {}, text
+    lines = text.splitlines()
+    # Find the closing '---' after the opening one.
+    close = next((i for i in range(1, len(lines)) if lines[i].strip() == "---"), None)
+    if close is None:
+        return {}, text
+    meta = _parse_yaml_subset(lines[1:close])
+    body = "\n".join(lines[close + 1 :]).strip()
+    return meta, body
+
+
+def _parse_yaml_subset(lines: Sequence[str]) -> dict[str, object]:
+    meta: dict[str, object] = {}
+    list_key: str | None = None
+    for raw in lines:
+        if not raw.strip() or raw.lstrip().startswith("#"):
+            continue
+        if list_key is not None and raw.lstrip().startswith("- "):
+            if not isinstance(meta.get(list_key), list):
+                meta[list_key] = []  # convert the empty-scalar placeholder to a list
+            meta[list_key].append(_unquote(raw.lstrip()[2:].strip()))  # type: ignore[union-attr]
+            continue
+        list_key = None
+        key, sep, value = raw.partition(":")
+        if not sep:
+            continue
+        key = key.strip()
+        value = value.strip()
+        if value == "":
+            list_key = key  # a block list may follow
+            meta[key] = ""
+        else:
+            meta[key] = _unquote(value)
+    return meta
+
+
+def _unquote(value: str) -> str:
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
+        return value[1:-1]
+    return value
+
+
+class SkillLibrary:
+    """Discovers skills in a directory and exposes them as a ContextSource.
+
+    ``active_skills`` are *pinned*: their full bodies join the prefix in addition
+    to the always-present catalog.
+    """
+
+    def __init__(self, directory: str | Path, active_skills: Sequence[str] | None = None) -> None:
+        self.directory = Path(directory) if directory else Path("skills")
+        self.active_skills: set[str] = set(active_skills or [])
+        self._skills: dict[str, Skill] = {}
+        if self.directory.is_dir():
+            self._load()
+
+    # --- discovery ---------------------------------------------------------
+
+    def _load(self) -> None:
+        for path in sorted(self.directory.iterdir()):
+            skill: Skill | None = None
+            if path.is_dir() and (path / "SKILL.md").is_file():
+                skill = self._load_skill_md(path / "SKILL.md", bundle_dir=path)
+            elif path.suffix.lower() == ".md":
+                skill = self._load_skill_md(path, bundle_dir=None)
+            elif path.suffix.lower() == ".toml":
+                skill = self._load_toml(path)
+            if skill is not None:
+                self._skills[skill.name] = skill
+
+    def _load_skill_md(self, path: Path, *, bundle_dir: Path | None) -> Skill | None:
+        text = path.read_text(encoding="utf-8")
+        meta, body = _split_frontmatter(text)
+        name = str(
+            meta.get("name") or path.stem
+            if not bundle_dir
+            else meta.get("name") or bundle_dir.name
+        )
+        description = str(meta.get("description") or _first_line(body))
+        resources: tuple[str, ...] = ()
+        if bundle_dir is not None:
+            resources = tuple(
+                _relpath(p)
+                for p in sorted(bundle_dir.rglob("*"))
+                if p.is_file() and p.name != "SKILL.md"
+            )
+        return Skill(
+            name=name, description=description, body=body, source=path, resources=resources
+        )
+
+    @staticmethod
+    def _load_toml(path: Path) -> Skill | None:
+        try:
+            values = tomllib.loads(path.read_text(encoding="utf-8"))
+        except (tomllib.TOMLDecodeError, OSError):
+            return None
+        body = str(values.get("system_prompt", ""))
+        return Skill(
+            name=str(values.get("name", path.stem)),
+            description=str(values.get("description", _first_line(body))),
+            body=body,
+            source=path,
+        )
+
+    # --- queries -----------------------------------------------------------
+
+    def available_skills(self) -> list[str]:
+        return sorted(self._skills)
+
+    def get(self, name: str) -> Skill | None:
+        return self._skills.get(name)
+
+    def describe(self) -> list[tuple[str, str]]:
+        return [(s.name, s.description) for s in (self._skills[n] for n in sorted(self._skills))]
+
+    # --- activation (pinning) ---------------------------------------------
+
+    def set_active(self, names: Sequence[str]) -> None:
+        self.active_skills = set(names)
+
+    def activate(self, name: str) -> bool:
+        """Toggle a skill's pin. Returns the resulting pinned state."""
+        if name in self.active_skills:
+            self.active_skills.discard(name)
+            return False
+        if name in self._skills:
+            self.active_skills.add(name)
+            return True
+        return False
+
+    # --- disclosure --------------------------------------------------------
+
+    def catalog_text(self) -> str:
+        entries = "\n".join(f"- {name}: {desc}" for name, desc in self.describe())
+        return (
+            "# Available skills\n"
+            "You have skills you can load on demand. When a task matches a "
+            "skill's purpose, call the `use_skill` tool with its name to load "
+            "the full instructions.\n\n" + entries
+        )
+
+    def system_additions(self) -> list[str]:
+        if not self._skills:
+            return []
+        additions = [self.catalog_text()]
+        for name in sorted(self.active_skills):
+            skill = self._skills.get(name)
+            if skill and skill.body:
+                additions.append(skill.body)
+        return additions
+
+    def use(self, name: str) -> str:
+        """Full disclosure for one skill (the ``use_skill`` tool result)."""
+        skill = self._skills.get(name)
+        if skill is None:
+            return f"Unknown skill: {name!r}. Available: {', '.join(self.available_skills())}"
+        out = [f"# Skill: {skill.name}\n", skill.body]
+        if skill.resources:
+            out.append("\nBundled files (read with read_file):")
+            out.extend(f"  {r}" for r in skill.resources)
+        return "\n".join(out)
+
+
+# Backward-compatible alias used elsewhere in the kernel.
+DirectorySkillStore = SkillLibrary
+SkillStore = SkillLibrary
+
+
+def _first_line(text: str) -> str:
+    for line in text.splitlines():
+        stripped = line.strip().lstrip("# ").strip()
+        if stripped:
+            return stripped
+    return ""
+
+
+def _relpath(path: Path) -> str:
+    try:
+        return os.path.relpath(path, Path.cwd())
+    except ValueError:  # pragma: no cover - different drive on Windows
+        return str(path)
+
+
+def make_skill_tool(library: SkillLibrary):
+    """Build the ``use_skill`` tool: load a skill's full body on demand."""
+    from agentkernel.tools.base import ToolSpec
+    from agentkernel.types import ToolResult
+
+    def handler(arguments: dict) -> ToolResult:
+        name = arguments["name"]
+        text = library.use(name)
+        is_error = text.startswith("Unknown skill:")
+        return ToolResult("", text, is_error=is_error)
+
+    return ToolSpec(
+        name="use_skill",
+        description=(
+            "Load the full instructions for one of your available skills by name. "
+            "Call this when a task matches a skill listed in 'Available skills'."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {"name": {"type": "string", "description": "The skill name."}},
+            "required": ["name"],
+            "additionalProperties": False,
+        },
+        handler=handler,
+        category="skills",
+    )

agentkernel/subagent.py

@@ -0,0 +1,161 @@
+"""Sub-agent delegation via a ``spawn`` tool (design §13).
+
+Re-entrancy (a tool handler calling ``Agent.run``) is already a kernel property;
+this exposes it to the *model* as an ordinary registered tool. The handler builds
+a child ``Agent`` with its own fresh context — optionally a focused system prompt
+and a subset of tools — runs the subtask, and returns the child's final answer.
+
+A depth limit prevents unbounded recursion: each child receives a ``spawn`` tool
+with one less depth budget, and at ``max_depth`` the child gets no ``spawn`` at
+all. Because the budget is captured per construction (not a shared counter), this
+stays correct under the loop's re-entrancy.
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import TYPE_CHECKING, Any
+
+from agentkernel.agent import Agent
+from agentkernel.context import ContextManager
+from agentkernel.profiles import Profile
+from agentkernel.telemetry import NullTelemetry
+from agentkernel.tools.base import ToolRegistry, ToolSpec
+from agentkernel.types import ToolResult
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from agentkernel.approval import Approver
+    from agentkernel.config import Config
+    from agentkernel.providers import Provider
+
+    ToolFactory = Callable[[str], list[ToolSpec]]
+
+_SPAWN_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "task": {
+            "type": "string",
+            "description": "The self-contained subtask for the sub-agent to complete.",
+        },
+        "system": {
+            "type": "string",
+            "description": "Optional system prompt focusing the sub-agent.",
+        },
+        "tools": {
+            "type": "array",
+            "items": {"type": "string"},
+            "description": "Optional subset of tool names the sub-agent may use.",
+        },
+        "worktree": {
+            "type": "boolean",
+            "description": (
+                "Run the sub-agent in an isolated throwaway git worktree so its "
+                "file edits don't collide with other work. Use for parallel agents "
+                "that edit code. Requires a git repo."
+            ),
+        },
+    },
+    "required": ["task"],
+    "additionalProperties": False,
+}
+
+
+def make_spawn_tool(
+    *,
+    provider: Provider,
+    base_specs: list[ToolSpec],
+    approver: Approver,
+    config: Config,
+    max_depth: int = 2,
+    depth: int = 1,
+    tool_factory: ToolFactory | None = None,
+) -> ToolSpec:
+    """Build a ``spawn`` tool. ``base_specs`` are the tools a child may use
+    (must NOT include a spawn tool — deeper spawns are added here recursively).
+
+    ``tool_factory(working_dir)`` rebuilds a fresh toolset bound to a directory;
+    it is required for ``worktree`` isolation (the child's file/shell tools must
+    point at the worktree, not the original working dir)."""
+
+    def _isolate(arguments: dict[str, Any]) -> tuple[Config, list[ToolSpec], object]:
+        """Return (child_config, child_specs, cleanup) honoring a worktree request."""
+        if not arguments.get("worktree") or tool_factory is None:
+            return config, base_specs, None
+        from agentkernel.worktree import WorktreeError, WorktreeManager
+
+        wm = WorktreeManager(config.working_dir)
+        if not wm.is_git_repo():
+            return config, base_specs, None
+        try:
+            path, branch = wm.create()
+        except WorktreeError:
+            return config, base_specs, None
+        return replace(config, working_dir=str(path)), tool_factory(str(path)), (wm, path, branch)
+
+    def handler(arguments: dict[str, Any]) -> ToolResult:
+        task = arguments["task"]
+        child_config, specs, cleanup = _isolate(arguments)
+
+        wanted = arguments.get("tools")
+        if wanted:
+            allowed = set(wanted)
+            specs = [s for s in specs if s.name in allowed]
+
+        child_registry = ToolRegistry()
+        for spec in specs:
+            child_registry.register(spec)
+        # Give the child its own (shallower) spawn ability until the limit.
+        if depth < max_depth:
+            child_registry.register(
+                make_spawn_tool(
+                    provider=provider,
+                    base_specs=base_specs,
+                    approver=approver,
+                    config=config,
+                    max_depth=max_depth,
+                    depth=depth + 1,
+                    tool_factory=tool_factory,
+                )
+            )
+
+        context = ContextManager(
+            budget=provider.context_window - child_config.output_reserve,
+            keep_recent_turns=child_config.keep_recent_turns,
+        )
+        child = Agent(
+            provider, child_registry, context, approver, NullTelemetry(), child_config
+        )
+        system = arguments.get("system")
+        profile = Profile(name="subagent", system_prompt=system) if system else None
+        try:
+            answer = child.run(task, profile=profile)
+        except Exception as exc:  # noqa: BLE001 - a child failure is a tool result
+            return ToolResult("", f"sub-agent error: {exc}", is_error=True)
+        return ToolResult("", answer + _finish_worktree(cleanup), data={"depth": depth})
+
+    return ToolSpec(
+        name="spawn",
+        description=(
+            "Delegate a self-contained subtask to a focused sub-agent and return "
+            "its final answer. Optionally restrict the sub-agent's tools, give it a "
+            "system prompt, or set worktree=true to isolate its file edits in a "
+            "throwaway git worktree. Use this to isolate a side investigation or to "
+            "parallelize independent work."
+        ),
+        parameters=_SPAWN_SCHEMA,
+        handler=handler,
+        category="agent",
+    )
+
+
+def _finish_worktree(cleanup: object) -> str:
+    """Remove a clean worktree, or keep one with changes and report where it is."""
+    if cleanup is None:
+        return ""
+    wm, path, branch = cleanup  # type: ignore[misc]
+    if wm.has_changes(path):
+        return f"\n\n[worktree kept at {path} on branch {branch} — it has changes to review]"
+    wm.remove(path)
+    return "\n\n[worktree removed — the sub-agent made no file changes]"

agentkernel/telemetry.py

@@ -0,0 +1,199 @@
+"""Per-turn telemetry (design §12).
+
+Writes one JSONL file per session under ``config.log_dir``. The record schema
+(below) is a stable interface for later phases — cost dashboards and the Phase-7
+self-improvement loop read it — so treat it as a contract, not throwaway logs.
+
+Redaction is the default: tool arguments are logged as a hash + length, never
+raw, and file contents never enter a record at all. ``verbose=True`` (the
+``--verbose-trace`` flag) includes raw arguments for local debugging only.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import uuid
+from collections.abc import Sequence
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Protocol
+
+if TYPE_CHECKING:
+    from agentkernel.context import CompactionEvent
+    from agentkernel.types import CompletionResponse
+
+
+@dataclass
+class ToolOutcome:
+    """What happened to one tool call this turn (for the trace)."""
+
+    name: str
+    arguments: dict[str, Any]
+    approved: bool | None  # True executed, False denied, None never reached the gate
+    is_error: bool
+
+
+@dataclass
+class Price:
+    """USD per million tokens for one model."""
+
+    input: float
+    output: float
+    cache_read: float = 0.0
+    cache_write: float = 0.0
+
+
+# TODO(owner): verify these seed prices against current provider pricing.
+DEFAULT_PRICES: dict[str, Price] = {
+    "claude-opus-4-8": Price(15.0, 75.0, 1.50, 18.75),
+    "claude-sonnet-4-6": Price(3.0, 15.0, 0.30, 3.75),
+    "claude-haiku-4-5-20251001": Price(1.0, 5.0, 0.10, 1.25),
+    "gpt-4o": Price(2.5, 10.0, 1.25, 0.0),
+    "gpt-4o-mini": Price(0.15, 0.60, 0.075, 0.0),
+}
+
+
+def estimate_cost(model: str, usage, prices: dict[str, Price]) -> float | None:
+    """Cost in USD, or None for an unknown model (tokens still logged)."""
+    price = prices.get(model)
+    if price is None:
+        return None
+    total = (
+        usage.input_tokens * price.input
+        + usage.output_tokens * price.output
+        + usage.cache_read_tokens * price.cache_read
+        + usage.cache_write_tokens * price.cache_write
+    )
+    return round(total / 1_000_000, 6)
+
+
+class Telemetry(Protocol):
+    """Minimal telemetry interface for the agent loop."""
+
+    @property
+    def model(self) -> str:
+        """Model name used for cost estimates."""
+        ...
+
+    @property
+    def prices(self) -> dict[str, Price]:
+        """Price table used for cost estimates."""
+        ...
+
+    def record_turn(
+        self,
+        iteration: int,
+        response: CompletionResponse,
+        *,
+        tool_outcomes: Sequence[ToolOutcome] = (),
+        compaction: CompactionEvent | None = None,
+    ) -> None:
+        ...
+
+
+class NullTelemetry:
+    """Records nothing. Used where tracing is not configured (and by tests)."""
+
+    def __init__(self, session_id: str | None = None) -> None:
+        self.session_id = session_id or str(uuid.uuid4())
+
+    @property
+    def model(self) -> str:
+        return "null"
+
+    @property
+    def prices(self) -> dict[str, Price]:
+        return DEFAULT_PRICES.copy()
+
+    def record_turn(
+        self,
+        iteration: int,
+        response: CompletionResponse,
+        *,
+        tool_outcomes: Sequence[ToolOutcome] = (),
+        compaction: CompactionEvent | None = None,
+    ) -> None:
+        return None
+
+
+def _redact(outcome: ToolOutcome, verbose: bool) -> dict[str, Any]:
+    entry: dict[str, Any] = {
+        "name": outcome.name,
+        "approved": outcome.approved,
+        "is_error": outcome.is_error,
+    }
+    serialized = json.dumps(outcome.arguments, sort_keys=True, default=str)
+    if verbose:
+        entry["arguments"] = outcome.arguments  # raw, local debugging only
+    else:
+        entry["args_sha256"] = hashlib.sha256(serialized.encode()).hexdigest()[:12]
+        entry["args_len"] = len(serialized)
+    return entry
+
+
+class JsonlTelemetry:
+    """Appends one JSON object per turn to ``<log_dir>/<session_id>.jsonl``."""
+
+    def __init__(
+        self,
+        log_dir: str,
+        model: str,
+        *,
+        session_id: str | None = None,
+        prices: dict[str, Price] | None = None,
+        verbose: bool = False,
+    ) -> None:
+        self.session_id = session_id or str(uuid.uuid4())
+        self._model = model
+        self._prices = DEFAULT_PRICES if prices is None else prices
+        self._verbose = verbose
+        directory = Path(log_dir)
+        directory.mkdir(parents=True, exist_ok=True)
+        self.path = directory / f"{self.session_id}.jsonl"
+        self._fh = self.path.open("a", encoding="utf-8")
+
+    @property
+    def model(self) -> str:
+        return self._model
+
+    @property
+    def prices(self) -> dict[str, Price]:
+        return self._prices
+
+    def record_turn(
+        self,
+        iteration: int,
+        response: CompletionResponse,
+        *,
+        tool_outcomes: Sequence[ToolOutcome] = (),
+        compaction: CompactionEvent | None = None,
+    ) -> None:
+        usage = response.usage
+        record = {
+            "ts": datetime.now(UTC).isoformat(),
+            "session_id": self.session_id,
+            "iteration": iteration,
+            "model": self._model,
+            "input_tokens": usage.input_tokens,
+            "output_tokens": usage.output_tokens,
+            "cache_read_tokens": usage.cache_read_tokens,
+            "cache_write_tokens": usage.cache_write_tokens,
+            "estimated_cost_usd": estimate_cost(self._model, usage, self._prices),
+            "tool_calls": [_redact(o, self._verbose) for o in tool_outcomes],
+            "stop_reason": response.stop_reason,
+            "compaction": None
+            if compaction is None
+            else {
+                "turns_collapsed": compaction.turns_collapsed,
+                "tokens_before": compaction.tokens_before,
+                "tokens_after": compaction.tokens_after,
+            },
+        }
+        self._fh.write(json.dumps(record) + "\n")
+        self._fh.flush()
+
+    def close(self) -> None:
+        if not self._fh.closed:
+            self._fh.close()

agentkernel/templates/README.md

@@ -0,0 +1,35 @@
+# Templates
+
+Copy-paste starting points for the things you author repeatedly. Each file is an
+annotated skeleton — read the comments, fill in the blanks, drop it in the right
+place.
+
+| Template | Create with | Lives in | Loaded by |
+|---|---|---|---|
+| [`SKILL.md`](SKILL.md) | `agentkernel new skill <name>` | `skills/<name>/SKILL.md` | discovered from `skills_dir` |
+| [`profile.toml`](profile.toml) | `agentkernel new profile <name>` | `profiles/<name>.toml` | `--profile <name>` |
+| [`loop.toml`](loop.toml) | `agentkernel new loop <name>` | `loops/<name>.toml` | `loop --file …` |
+| [`eval-suite.toml`](eval-suite.toml) | `agentkernel new eval <name>` | `evals/<name>.toml` | `eval --suite …` |
+| [`mcp-servers.toml`](mcp-servers.toml) | (copy by hand) | your `agentkernel.toml` | MCP client at startup |
+| [`tool_module.py`](tool_module.py) | (copy by hand) | wherever you load tools | your runtime / plugin loader |
+
+## Scaffolding command
+
+`agentkernel new <kind> <name>` copies the matching template into place with the
+name filled in (the `{{name}}` placeholder is substituted):
+
+```bash
+agentkernel new skill   commit-helper      # -> skills/commit-helper/SKILL.md
+agentkernel new profile reviewer-strict    # -> profiles/reviewer-strict.toml
+agentkernel new loop    until-docs-build    # -> loops/until-docs-build.toml
+agentkernel new eval    smoke               # -> evals/smoke.toml
+```
+
+It refuses to overwrite an existing file unless you pass `--force`, and rejects
+names containing path separators. `new` finds this `templates/` directory by
+walking up from the current directory, so run it from inside the project.
+
+## See also
+
+The bundled starter content built from these templates: [`skills/`](../skills),
+[`profiles/`](../profiles), and [`loops/`](../loops).

agentkernel/templates/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: {{name}}
+# One line that does double duty: WHAT this skill does AND WHEN to use it.
+# Be specific about trigger phrases — this line is all the model sees until it
+# decides to load the skill, so it's the whole basis for that decision.
+description: <what this does>. Use when <specific situations / phrases that should trigger it>.
+---
+
+# {{name}}
+
+<!--
+Progressive disclosure: only the name + description above sit in the prompt until
+the model loads this skill with the use_skill tool. Keep the body focused and
+actionable — instructions the model follows, not background prose. A few hundred
+lines max; if it's growing, split detail into bundled files next to this one and
+point at them.
+-->
+
+## When to use
+- <concrete situation 1>
+- <concrete situation 2>
+
+## Steps
+1. <first thing to do>
+2. <next thing>
+
+## Output format
+<How the result should be structured, if it matters.>