agent-toolkit-cli 1.11.0__py3-none-win_amd64.whl

agent_toolkit/compiler/model.py

@@ -0,0 +1,182 @@
+"""
+Canonical intermediate representation for agent-toolkit capabilities.
+
+This module defines the platform-neutral capability model that all canonical
+sources (SKILL.md, AGENT.md, loop.yaml, etc.) are parsed into before being
+compiled into target-specific artifacts.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+
+class Stability(str, Enum):
+    STABLE = "stable"
+    EXPERIMENTAL = "experimental"
+    DEPRECATED = "deprecated"
+
+
+class ModelClass(str, Enum):
+    """Abstract model tier — target adapters map to platform-specific models."""
+
+    FAST = "fast"
+    BALANCED = "balanced"
+    DEEP = "deep"
+    INHERIT = "inherit"
+
+
+class AbstractTool(str, Enum):
+    """Platform-neutral tool vocabulary. Adapters map to native tool names."""
+
+    FS_READ = "fs.read"
+    FS_SEARCH = "fs.search"
+    FS_WRITE = "fs.write"
+    SHELL_READONLY = "shell.readonly"
+    SHELL_EXECUTE = "shell.execute"
+    GIT_READ = "git.read"
+    GIT_WRITE = "git.write"
+    WEB_SEARCH = "web.search"
+    WEB_FETCH = "web.fetch"
+    AGENT_DELEGATE = "agent.delegate"
+    USER_ASK = "user.ask"
+
+
+@dataclass
+class Requirement:
+    """A runtime requirement for a capability."""
+
+    name: str
+    description: str
+    install_url: str = ""
+    required: bool = False
+    env_var: str = ""  # if env-var based, not binary
+
+
+@dataclass
+class SecurityPolicy:
+    approval_required: bool = False
+    default_enabled: bool = True
+    rationale: str = ""
+    no_dangerous_bypass: bool = True
+
+
+@dataclass
+class Provenance:
+    """Tracks the source of a capability for audit."""
+
+    source_path: Path
+    source_hash: str = ""
+    generated_by: str = "agent-toolkit"
+    generator_version: str = ""
+
+
+@dataclass
+class Skill:
+    """A canonical skill parsed from skills/<domain>/<name>/SKILL.md."""
+
+    id: str  # e.g. "core/assistant"
+    name: str  # must match directory name
+    domain: str  # e.g. "core"
+    description: str
+    stability: Stability = Stability.STABLE
+    source_path: Path = field(default_factory=Path)
+    tags: list[str] = field(default_factory=list)
+    requires: list[Requirement] = field(default_factory=list)
+    compatibility: str = ""  # human-readable compat note
+    metadata: dict[str, Any] = field(default_factory=dict)
+    provenance: Provenance | None = None
+
+
+@dataclass
+class Agent:
+    """A canonical agent persona parsed from agents/<name>/AGENT.md."""
+
+    id: str
+    name: str
+    description: str
+    instructions: str  # body of AGENT.md
+    model_class: ModelClass = ModelClass.INHERIT
+    max_turns: int = 0  # 0 = platform default
+    allowed_tools: list[AbstractTool] = field(default_factory=list)
+    denied_tools: list[AbstractTool] = field(default_factory=list)
+    delegates_to: list[str] = field(default_factory=list)
+    read_only: bool = False
+    background_eligible: bool = False
+    dependent_skills: list[str] = field(default_factory=list)
+    dependent_mcp: list[str] = field(default_factory=list)
+    stability: Stability = Stability.STABLE
+    source_path: Path = field(default_factory=Path)
+    metadata: dict[str, Any] = field(default_factory=dict)
+    provenance: Provenance | None = None
+
+
+@dataclass
+class Product:
+    """A distributable plugin/bundle product parsed from distributions/products.yaml."""
+
+    id: str
+    name: str
+    description: str
+    stability: Stability = Stability.STABLE
+    included_skills: list[str] = field(default_factory=list)  # skill IDs
+    included_agents: list[str] = field(default_factory=list)  # agent IDs
+    included_hooks: list[str] = field(default_factory=list)  # hook IDs
+    included_mcp: list[str] = field(default_factory=list)  # MCP provider IDs
+    excluded: list[str] = field(default_factory=list)
+    requires: list[Requirement] = field(default_factory=list)
+    security: SecurityPolicy = field(default_factory=SecurityPolicy)
+    target_overrides: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class CanonicalGraph:
+    """The resolved capability graph — all canonical sources loaded and validated."""
+
+    skills: dict[str, Skill] = field(default_factory=dict)  # id → Skill
+    agents: dict[str, Agent] = field(default_factory=dict)  # id → Agent
+    products: dict[str, Product] = field(default_factory=dict)  # id → Product
+    errors: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+    @property
+    def is_valid(self) -> bool:
+        return len(self.errors) == 0
+
+
+@dataclass
+class CompilationResult:
+    """Result from a target adapter compilation."""
+
+    target: str
+    product: str
+    emitted: list[str] = field(default_factory=list)  # capability IDs
+    transformed: list[str] = field(default_factory=list)  # with degradation
+    omitted: list[str] = field(default_factory=list)  # safely dropped
+    unsupported: list[str] = field(default_factory=list)  # not supported
+    warnings: list[str] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+    artifacts: list[Path] = field(default_factory=list)
+
+    @property
+    def is_valid(self) -> bool:
+        return len(self.errors) == 0
+
+    def report(self) -> str:
+        lines = [f"Target: {self.target}  Product: {self.product}"]
+        if self.emitted:
+            lines.append(f"  ✓ emitted:     {', '.join(self.emitted)}")
+        if self.transformed:
+            lines.append(f"  ~ transformed: {', '.join(self.transformed)}")
+        if self.omitted:
+            lines.append(f"  - omitted:     {', '.join(self.omitted)}")
+        if self.unsupported:
+            lines.append(f"  ✗ unsupported: {', '.join(self.unsupported)}")
+        for w in self.warnings:
+            lines.append(f"  ⚠ {w}")
+        for e in self.errors:
+            lines.append(f"  ✗ ERROR: {e}")
+        return "\n".join(lines)

agent_toolkit/compiler/provenance.py

@@ -0,0 +1,140 @@
+"""
+Provenance tracking for generated compiler artifacts.
+
+Every generated plugin bundle gets a .provenance.json sidecar that records:
+- Generator version
+- Source file paths and digests for each artifact
+- Build metadata (no timestamps in reproducible content)
+
+This enables drift detection: agent-toolkit plugin check compares
+artifact digests against provenance to catch manual edits.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class ArtifactRecord:
+    """Provenance record for a single generated file."""
+
+    path: str  # relative path from plugin root
+    source_file: str  # canonical source (e.g. skills/core/assistant/SKILL.md)
+    source_digest: str  # SHA256[:12] of source content
+    generated_digest: str  # SHA256[:12] of generated content
+
+
+@dataclass
+class ProvenanceManifest:
+    """Provenance manifest for a complete plugin bundle."""
+
+    generator_version: str
+    product: str
+    target: str
+    artifacts: list[ArtifactRecord] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "generatorVersion": self.generator_version,
+            "product": self.product,
+            "target": self.target,
+            "artifacts": [
+                {
+                    "path": a.path,
+                    "sourceFile": a.source_file,
+                    "sourceDigest": a.source_digest,
+                    "generatedDigest": a.generated_digest,
+                }
+                for a in self.artifacts
+            ],
+        }
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), indent=2) + "\n"
+
+
+def file_digest(path: Path) -> str:
+    """SHA256[:12] of file content."""
+    if not path.exists():
+        return "missing"
+    return hashlib.sha256(path.read_bytes()).hexdigest()[:12]
+
+
+def write_provenance(
+    out_dir: Path,
+    product_id: str,
+    target_id: str,
+    artifact_records: list[ArtifactRecord],
+) -> Path:
+    """Write .provenance.json to the plugin bundle root."""
+    try:
+        from agent_toolkit import __version__
+
+        version = __version__
+    except ImportError:
+        version = "unknown"
+
+    manifest = ProvenanceManifest(
+        generator_version=version,
+        product=product_id,
+        target=target_id,
+        artifacts=artifact_records,
+    )
+    provenance_path = out_dir / ".provenance.json"
+    provenance_path.write_text(manifest.to_json(), encoding="utf-8")
+    return provenance_path
+
+
+def load_provenance(path: Path) -> ProvenanceManifest | None:
+    """Load a .provenance.json manifest. Returns None if missing or invalid."""
+    if not path.is_file():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+
+    artifacts = [
+        ArtifactRecord(
+            path=item["path"],
+            source_file=item["sourceFile"],
+            source_digest=item["sourceDigest"],
+            generated_digest=item["generatedDigest"],
+        )
+        for item in data.get("artifacts", [])
+    ]
+    return ProvenanceManifest(
+        generator_version=data.get("generatorVersion", "unknown"),
+        product=data.get("product", ""),
+        target=data.get("target", ""),
+        artifacts=artifacts,
+    )
+
+
+def verify_generated_digests(
+    plugins_dir: Path,
+    provenance_path: Path,
+) -> list[str]:
+    """Compare recorded generatedDigest values to current artifact content.
+
+    Artifact paths in the manifest are relative to *plugins_dir* (compiler
+    output root). Returns human-readable drift messages (empty when in sync).
+    """
+    manifest = load_provenance(provenance_path)
+    if manifest is None:
+        return []
+
+    errors: list[str] = []
+    for record in manifest.artifacts:
+        artifact_path = plugins_dir / record.path
+        current = file_digest(artifact_path)
+        if current != record.generated_digest:
+            errors.append(
+                f"provenance digest drift: {record.path} "
+                f"(expected {record.generated_digest}, got {current})"
+            )
+    return errors

agent_toolkit/compiler/registry_emit.py

@@ -0,0 +1,263 @@
+"""Emit hooks and MCP configurations from canonical registries into target formats."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from agent_toolkit.compiler.hook_registry import HookDefinition, load_hooks
+from agent_toolkit.compiler.mcp_registry import McpProvider, load_registry
+
+_BUNDLE_SCRIPTS_PREFIX = "hooks/scripts"
+
+# Canonical event → Claude Code hook event name
+_CLAUDE_HOOK_EVENTS: dict[str, str] = {
+    "session.start": "SessionStart",
+    "session.end": "SessionEnd",
+    "tool.before": "PreToolUse",
+    "tool.after": "PostToolUse",
+    "prompt.before_submit": "UserPromptSubmit",
+}
+
+
+def _hooks_dict(hooks_dir: Path) -> dict[str, HookDefinition]:
+    hooks, _errors = load_hooks(hooks_dir)
+    return hooks
+
+
+def _mcp_dict(registry_dir: Path) -> dict[str, McpProvider]:
+    providers, _errors = load_registry(registry_dir)
+    return providers
+
+
+def resolve_hook_ids(
+    product_hooks: list[str],
+    *,
+    target_id: str,
+    hooks_dir: Path,
+    emit_registries: bool = False,
+) -> list[str]:
+    """Return hook IDs to emit for a product/target."""
+    registry = _hooks_dict(hooks_dir)
+    if product_hooks:
+        return [hid for hid in product_hooks if hid in registry]
+    if not emit_registries:
+        return []
+    return [hook.id for hook in registry.values() if hook.is_supported_for(target_id)]
+
+
+def resolve_mcp_ids(
+    product_mcp: list[str],
+    *,
+    target_id: str,
+    registry_dir: Path,
+    emit_registries: bool = False,
+) -> list[str]:
+    """Return MCP provider IDs to emit for a product/target."""
+    registry = _mcp_dict(registry_dir)
+    if product_mcp:
+        return [pid for pid in product_mcp if pid in registry]
+    if not emit_registries:
+        return []
+    return [provider.id for provider in registry.values() if provider.is_supported_for(target_id)]
+
+
+def hook_script_basename(command: list[str]) -> str | None:
+    """Return the script filename from a command handler, if present."""
+    if len(command) < 2:
+        return None
+    script = command[-1]
+    if script.endswith((".sh", ".py", ".bash")):
+        return Path(script).name
+    return None
+
+
+def hook_script_source(command: list[str], repo_root: Path) -> Path | None:
+    """Resolve the repo-relative script path referenced by a hook command."""
+    if len(command) < 2:
+        return None
+    script = Path(command[-1])
+    if script.is_absolute():
+        return script if script.is_file() else None
+    candidate = repo_root / script
+    return candidate if candidate.is_file() else None
+
+
+def rewrite_hook_command_for_bundle(
+    command: list[str],
+    *,
+    bundle_scripts_prefix: str = _BUNDLE_SCRIPTS_PREFIX,
+) -> list[str]:
+    """Rewrite repo-relative script paths to plugin-bundle-relative paths."""
+    if len(command) < 2:
+        return command
+    script = command[-1]
+    if script.startswith("/") or "://" in script:
+        return command
+    if "/" not in script and not script.endswith((".sh", ".py", ".bash")):
+        return command
+    name = Path(script).name
+    return [*command[:-1], f"{bundle_scripts_prefix}/{name}"]
+
+
+def emit_claude_hooks_json(
+    hook_ids: list[str],
+    hooks_dir: Path,
+    target_id: str = "claude-code",
+    *,
+    bundle_relative: bool = False,
+) -> dict | None:
+    """Build Claude Code hooks/hooks.json content from canonical hook IDs."""
+    registry = _hooks_dict(hooks_dir)
+    hooks_block: dict[str, list[dict]] = {}
+
+    for hook_id in hook_ids:
+        hook = registry.get(hook_id)
+        if hook is None or not hook.is_supported_for(target_id):
+            continue
+        event_name = _CLAUDE_HOOK_EVENTS.get(hook.event, hook.event)
+        if hook.handler_type != "command" or not hook.command:
+            continue
+        command = rewrite_hook_command_for_bundle(hook.command) if bundle_relative else hook.command
+        entry = {
+            "type": "command",
+            "command": " ".join(command),
+            "timeout": hook.timeout_ms,
+        }
+        hooks_block.setdefault(event_name, []).append(entry)
+
+    if not hooks_block:
+        return None
+    return {"hooks": hooks_block}
+
+
+def emit_claude_mcp_json(
+    provider_ids: list[str],
+    registry_dir: Path,
+    target_id: str = "claude-code",
+) -> dict | None:
+    """Build Claude Code .mcp.json content from canonical MCP provider IDs."""
+    registry = _mcp_dict(registry_dir)
+    servers: dict[str, dict] = {}
+
+    for provider_id in provider_ids:
+        provider = registry.get(provider_id)
+        if provider is None or not provider.is_supported_for(target_id):
+            continue
+        env = {var: f"${{{var}}}" for var in provider.env_vars}
+        if provider.package.startswith("@"):
+            servers[provider_id] = {
+                "command": "npx",
+                "args": ["-y", provider.package],
+                "env": env,
+            }
+        else:
+            servers[provider_id] = {
+                "command": provider.package or provider_id,
+                "env": env,
+            }
+
+    if not servers:
+        return None
+    return {"mcpServers": servers}
+
+
+def hooks_json_text(
+    hook_ids: list[str],
+    hooks_dir: Path,
+    target_id: str = "claude-code",
+    *,
+    bundle_relative: bool = False,
+) -> str | None:
+    payload = emit_claude_hooks_json(
+        hook_ids,
+        hooks_dir,
+        target_id,
+        bundle_relative=bundle_relative,
+    )
+    if payload is None:
+        return None
+    return json.dumps(payload, indent=2) + "\n"
+
+
+def mcp_json_text(
+    provider_ids: list[str],
+    registry_dir: Path,
+    target_id: str = "claude-code",
+) -> str | None:
+    payload = emit_claude_mcp_json(provider_ids, registry_dir, target_id)
+    if payload is None:
+        return None
+    return json.dumps(payload, indent=2) + "\n"
+
+
+def emit_agent_plugins_mcp_json(
+    provider_ids: list[str],
+    registry_dir: Path,
+    target_id: str = "agent-plugins",
+) -> dict | None:
+    """Build Agent Plugins 1.0 mcp.json content per spec §7.2.
+
+    Uses stdio transport with PLUGIN_ROOT/PLUGIN_DATA aware cwd/env.
+    """
+    registry = _mcp_dict(registry_dir)
+    servers: dict[str, dict] = {}
+
+    for provider_id in provider_ids:
+        provider = registry.get(provider_id)
+        if provider is None:
+            continue
+        # Only emit if provider has some tool definition (avoid empty)
+        # Use docker for ghcr, npx for npm packages
+        # Use strict host check to avoid substring bypass (CodeQL: py/incomplete-url-substring-sanitization)
+        if provider.package.split("/", 1)[0] == "ghcr.io":
+            servers[provider_id] = {
+                "type": "stdio",
+                "command": "docker",
+                "args": [
+                    "run",
+                    "-i",
+                    "--rm",
+                    "-e",
+                    provider.env_vars[0] if provider.env_vars else "TOKEN",
+                    provider.package,
+                ],
+                "cwd": "${PLUGIN_ROOT}",
+            }
+            if provider.env_vars:
+                servers[provider_id]["env"] = {var: f"${{{var}}}" for var in provider.env_vars}
+        elif provider.package.startswith("@"):
+            servers[provider_id] = {
+                "type": "stdio",
+                "command": "npx",
+                "args": ["-y", provider.package],
+                "cwd": "${PLUGIN_ROOT}",
+            }
+            if provider.env_vars:
+                servers[provider_id]["env"] = {var: f"${{{var}}}" for var in provider.env_vars}
+        else:
+            servers[provider_id] = {
+                "type": "stdio",
+                "command": provider.package or provider_id,
+                "cwd": "${PLUGIN_ROOT}",
+            }
+            if provider.env_vars:
+                servers[provider_id]["env"] = {var: f"${{{var}}}" for var in provider.env_vars}
+
+    if not servers:
+        return None
+    return {
+        "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+        "mcpServers": servers,
+    }
+
+
+def mcp_json_text_agent_plugins(
+    provider_ids: list[str],
+    registry_dir: Path,
+    target_id: str = "agent-plugins",
+) -> str | None:
+    payload = emit_agent_plugins_mcp_json(provider_ids, registry_dir, target_id)
+    if payload is None:
+        return None
+    return json.dumps(payload, indent=2) + "\n"

agent_toolkit/compiler/target_registry.py

@@ -0,0 +1,122 @@
+"""Load declarative compile-target registry from capabilities/targets/registry.yaml."""
+
+from __future__ import annotations
+
+import importlib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from agent_toolkit._paths import toolkit_root
+
+
+@dataclass(frozen=True)
+class TargetSpec:
+    id: str
+    adapter: str
+    aliases: tuple[str, ...]
+    build: bool
+    diff: bool
+    release: bool
+
+
+_REGISTRY_REL_PATHS = (
+    Path("capabilities/targets/registry.yaml"),
+    Path("schemas/targets-registry.yaml"),
+)
+
+
+def _repo_root(repo_root: Path | None = None) -> Path:
+    if repo_root is not None:
+        return repo_root
+    root = toolkit_root()
+    for rel in _REGISTRY_REL_PATHS:
+        if (root / rel).is_file():
+            return root
+        if (root.parent / rel).is_file():
+            return root.parent
+    return root
+
+
+def _registry_path(repo_root: Path) -> Path:
+    for rel in _REGISTRY_REL_PATHS:
+        path = repo_root / rel
+        if path.is_file():
+            return path
+    raise FileNotFoundError(
+        "Target registry not found. Expected one of: "
+        + ", ".join(str(p) for p in _REGISTRY_REL_PATHS)
+    )
+
+
+def _parse_target(raw: dict[str, Any]) -> TargetSpec:
+    commands = raw.get("commands") or {}
+    adapter = raw.get("adapter")
+    if not adapter and raw.get("adapter_module") and raw.get("adapter_class"):
+        adapter = f"{raw['adapter_module']}.{raw['adapter_class']}"
+    if not adapter:
+        raise ValueError(f"Target {raw.get('id')!r} missing adapter path")
+    return TargetSpec(
+        id=str(raw["id"]),
+        adapter=str(adapter),
+        aliases=tuple(str(a) for a in (raw.get("aliases") or [])),
+        build=bool(commands.get("build", True)),
+        diff=bool(commands.get("diff", False)),
+        release=bool(commands.get("release", True)),
+    )
+
+
+def load_target_registry(repo_root: Path | None = None) -> list[TargetSpec]:
+    root = _repo_root(repo_root)
+    data = yaml.safe_load(_registry_path(root).read_text(encoding="utf-8")) or {}
+    return [_parse_target(entry) for entry in data.get("targets") or []]
+
+
+def registry_by_id(registry: list[TargetSpec] | None = None) -> dict[str, TargetSpec]:
+    specs = registry or load_target_registry()
+    out: dict[str, TargetSpec] = {}
+    for spec in specs:
+        out[spec.id] = spec
+        for alias in spec.aliases:
+            out[alias] = spec
+    return out
+
+
+def resolve_target_id(target_id: str, registry: list[TargetSpec] | None = None) -> str:
+    by_id = registry_by_id(registry)
+    spec = by_id.get(target_id)
+    return spec.id if spec else target_id
+
+
+def target_ids_for(command: str, registry: list[TargetSpec] | None = None) -> list[str]:
+    specs = registry or load_target_registry()
+    attr = {"build": "build", "diff": "diff", "release": "release"}[command]
+    return [spec.id for spec in specs if getattr(spec, attr)]
+
+
+def available_target_ids(
+    repo_root: Path | None = None,
+    *,
+    command: str = "build",
+) -> list[str]:
+    return target_ids_for(command, load_target_registry(repo_root))
+
+
+def adapter_import_path(spec: TargetSpec) -> str:
+    return spec.adapter
+
+
+def resolve_adapter_class(target_id: str, repo_root: Path | None = None):
+    """Import and return adapter class for target id or alias."""
+    by_id = registry_by_id(load_target_registry(repo_root))
+    spec = by_id.get(target_id)
+    if spec is None:
+        return None
+    module_path, cls_name = spec.adapter.rsplit(".", 1)
+    try:
+        mod = importlib.import_module(module_path)
+        return getattr(mod, cls_name)
+    except (ImportError, AttributeError):
+        return None