agent-devkit 0.1.6 → 0.3.0

package/runtime/cli/aikit/contribution.py

@@ -0,0 +1,235 @@
+"""Contribution preparation MVP for local Agent DevKit extensions."""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+from cli.aikit.extensions import load_extensions
+from cli.aikit.memory import sanitize_segment
+
+
+CONTRIBUTION_SCHEMA_VERSION = "agent-devkit.contribution/v1"
+SECRET_PATTERN = re.compile(r"(token|secret|password|api[_-]?key|pat)\s*[:=]", re.IGNORECASE)
+PRIVATE_URL_PATTERN = re.compile(r"https?://(?:localhost|127\.0\.0\.1|10\.|192\.168\.|172\.(?:1[6-9]|2\d|3[0-1])\.)", re.IGNORECASE)
+LOCAL_PATH_PATTERN = re.compile(r"(/Users/|/home/|C:\\\\Users\\\\)")
+PII_PATTERN = re.compile(r"\b\d{3}\.\d{3}\.\d{3}-\d{2}\b|\b[\w.+-]+@[\w.-]+\.[A-Za-z]{2,}\b")
+CORPORATE_TERMS_ENV = "AGENT_DEVKIT_CORPORATE_TERMS"
+
+
+def contribution_list() -> dict[str, Any]:
+    extensions = load_extensions()["extensions"]
+    return {
+        "kind": "contributions",
+        "schema_version": CONTRIBUTION_SCHEMA_VERSION,
+        "status": "ok",
+        "items": [
+            {
+                "id": item.get("id"),
+                "path": sanitize_path_for_report(item.get("path")),
+                "path_sanitized": True,
+                "enabled": item.get("enabled") is True,
+            }
+            for item in extensions
+        ],
+    }
+
+
+def contribution_checklist(extension_id: str) -> dict[str, Any]:
+    extension = find_extension(extension_id)
+    if not extension:
+        return {
+            "kind": "contribution-checklist",
+            "schema_version": CONTRIBUTION_SCHEMA_VERSION,
+            "status": "blocked",
+            "exit_code": 2,
+            "extension_id": extension_id,
+            "checks": [{"id": "extension-exists", "status": "failed"}],
+        }
+    checks = contribution_checks(Path(str(extension.get("path") or "")))
+    return {
+        "kind": "contribution-checklist",
+        "schema_version": CONTRIBUTION_SCHEMA_VERSION,
+        "status": "passed" if all(check["status"] == "passed" for check in checks) else "blocked",
+        "exit_code": 0 if all(check["status"] == "passed" for check in checks) else 2,
+        "extension_id": extension_id,
+        "checks": checks,
+        "requires_human_confirmation_for_pr": True,
+    }
+
+
+def contribution_validate(extension_id: str) -> dict[str, Any]:
+    payload = contribution_checklist(extension_id)
+    payload["kind"] = "contribution-validation"
+    return payload
+
+
+def contribution_prepare(extension_id: str) -> dict[str, Any]:
+    checklist = contribution_checklist(extension_id)
+    status = "planned" if checklist["status"] == "passed" else "blocked"
+    return {
+        "kind": "contribution-prepare",
+        "schema_version": CONTRIBUTION_SCHEMA_VERSION,
+        "status": status,
+        "exit_code": 0 if status == "planned" else 2,
+        "extension_id": extension_id,
+        "checklist": checklist,
+        "creates_pr": False,
+    }
+
+
+def contribution_pr(extension_id: str, *, dry_run: bool = True, yes: bool = False) -> dict[str, Any]:
+    checklist = contribution_checklist(extension_id)
+    safe_id = sanitize_segment(extension_id)
+    plan = {
+        "external_writes": True,
+        "requires_confirmation": True,
+        "mode": "dry-run" if dry_run or not yes else "apply",
+        "commands": [
+            f"git checkout -b feat/contribution-{safe_id}",
+            "git add <sanitized-extension-files>",
+            f"git commit -m 'Add Agent DevKit contribution {safe_id}'",
+            "gh pr create --fill",
+        ],
+        "stores_secret": False,
+        "local_paths_sanitized": True,
+    }
+    if checklist["status"] != "passed":
+        return {
+            "kind": "contribution-pr",
+            "schema_version": CONTRIBUTION_SCHEMA_VERSION,
+            "status": "blocked",
+            "exit_code": 2,
+            "extension_id": extension_id,
+            "checklist": checklist,
+            "plan": plan,
+            "reason": "contribution_checklist_failed",
+        }
+    if dry_run or not yes:
+        return {
+            "kind": "contribution-pr",
+            "schema_version": CONTRIBUTION_SCHEMA_VERSION,
+            "status": "planned",
+            "exit_code": 0,
+            "extension_id": extension_id,
+            "checklist": checklist,
+            "plan": plan,
+            "message": "PR contribution plan generated in report-only mode.",
+        }
+    return {
+        "kind": "contribution-pr",
+        "schema_version": CONTRIBUTION_SCHEMA_VERSION,
+        "status": "blocked",
+        "exit_code": 2,
+        "extension_id": extension_id,
+        "checklist": checklist,
+        "plan": plan,
+        "reason": "external_write_confirmation_required",
+        "next_steps": [
+            "Review the generated plan and run the git/gh commands manually or through a future confirmed writer.",
+            "Agent DevKit does not open contribution PRs automatically from this runtime path.",
+        ],
+    }
+
+
+def contribution_review(extension_id: str) -> dict[str, Any]:
+    checklist = contribution_checklist(extension_id)
+    return {
+        "kind": "contribution-review",
+        "schema_version": CONTRIBUTION_SCHEMA_VERSION,
+        "status": checklist["status"],
+        "exit_code": 0 if checklist["status"] == "passed" else 2,
+        "extension_id": extension_id,
+        "findings": [check for check in checklist["checks"] if check["status"] != "passed"],
+    }
+
+
+def find_extension(extension_id: str) -> dict[str, Any] | None:
+    for item in load_extensions()["extensions"]:
+        if item.get("id") == extension_id:
+            return item
+    return None
+
+
+def contribution_checks(path: Path) -> list[dict[str, Any]]:
+    text = read_extension_text(path)
+    corporate_terms = configured_corporate_terms()
+    structure = extension_structure_kind(path)
+    return [
+        {"id": "extension-exists", "status": "passed" if path.exists() else "failed"},
+        {
+            "id": "recognized-extension-structure",
+            "status": "passed" if structure else "failed",
+            "type": structure or "unknown",
+        },
+        {"id": "no-secret-literals", "status": "failed" if SECRET_PATTERN.search(text) else "passed"},
+        {"id": "no-private-url", "status": "failed" if PRIVATE_URL_PATTERN.search(text) else "passed"},
+        {"id": "no-local-path", "status": "failed" if LOCAL_PATH_PATTERN.search(text) else "passed"},
+        {"id": "no-pii", "status": "failed" if PII_PATTERN.search(text) else "passed"},
+        {
+            "id": "no-corporate-name",
+            "status": "failed" if contains_configured_corporate_term(text, corporate_terms) else "passed",
+            "terms_configured": len(corporate_terms),
+        },
+        {"id": "human-pr-confirmation", "status": "passed"},
+    ]
+
+
+def read_extension_text(path: Path) -> str:
+    if not path.exists():
+        return ""
+    if path.is_file():
+        return path.read_text(encoding="utf-8", errors="ignore")[:200_000]
+    chunks = []
+    for child in sorted(path.rglob("*")):
+        if child.is_file() and child.suffix in {".md", ".yaml", ".yml", ".json", ".py", ".sh", ".txt"}:
+            chunks.append(child.read_text(encoding="utf-8", errors="ignore")[:50_000])
+    return "\n".join(chunks)[:300_000]
+
+
+def extension_structure_kind(path: Path) -> str | None:
+    if not path.exists():
+        return None
+    if path.is_file():
+        if path.suffix in {".py", ".sh"}:
+            return "script"
+        if path.suffix in {".md", ".yaml", ".yml", ".json"}:
+            return "file"
+        return None
+    if (path / "agent.yaml").exists():
+        return "agent"
+    if (path / "SKILL.md").exists() or (path / "skill.md").exists():
+        return "skill"
+    if any((path / name).exists() for name in ("workflow.yaml", "workflow.yml")):
+        return "workflow"
+    if any(path.rglob("agent.yaml")):
+        return "agent"
+    if any(path.rglob("SKILL.md")) or any(path.rglob("skill.md")):
+        return "skill"
+    if any(path.rglob("workflow.yaml")) or any(path.rglob("workflow.yml")):
+        return "workflow"
+    if any(child.is_file() and child.suffix in {".py", ".sh"} for child in path.rglob("*")):
+        return "script"
+    return None
+
+
+def sanitize_path_for_report(value: Any) -> str | None:
+    if not value:
+        return None
+    name = Path(str(value)).name
+    return f"<local-extension-path>/{sanitize_segment(name)}"
+
+
+def configured_corporate_terms() -> list[str]:
+    raw = os.environ.get(CORPORATE_TERMS_ENV, "")
+    terms = [term.strip().lower() for term in re.split(r"[,;\n]+", raw) if len(term.strip()) >= 3]
+    return sorted(set(terms))
+
+
+def contains_configured_corporate_term(text: str, terms: list[str]) -> bool:
+    if not terms:
+        return False
+    lowered = text.lower()
+    return any(term in lowered for term in terms)

package/runtime/cli/aikit/core/__init__.py

@@ -0,0 +1 @@
+"""Reusable Agent DevKit core package."""

package/runtime/cli/aikit/core/capability_contract.py

@@ -0,0 +1,112 @@
+"""Canonical capability contract helpers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from cli.aikit.core.requests import CapabilityRunRequest
+from cli.aikit.runtime_paths import ROOT
+from cli.aikit.write_policy import write_policy_metadata
+
+
+def capability_policy(manifest: dict[str, Any]) -> dict[str, Any]:
+    return write_policy_metadata(manifest.get("write_policy"))
+
+
+def normalize_capability_artifacts(value: Any) -> list[dict[str, Any]]:
+    artifacts = value if isinstance(value, list) else []
+    normalized: list[dict[str, Any]] = []
+    for item in artifacts:
+        if isinstance(item, str):
+            normalized.append(
+                {
+                    "path": item,
+                    "kind": artifact_kind(item),
+                    "description": "",
+                    "sensitive": False,
+                    "created": None,
+                }
+            )
+            continue
+        if isinstance(item, dict):
+            path = str(item.get("path") or item.get("ref") or "").strip()
+            normalized.append(
+                {
+                    "path": path,
+                    "kind": str(item.get("kind") or artifact_kind(path)),
+                    "description": str(item.get("description") or ""),
+                    "sensitive": bool(item.get("sensitive", False)),
+                    "created": item.get("created"),
+                }
+            )
+    return normalized
+
+
+def artifact_kind(path: str) -> str:
+    suffix = Path(path).suffix.lower().lstrip(".")
+    if suffix in {"md", "markdown"}:
+        return "markdown"
+    if suffix in {"json"}:
+        return "json"
+    if suffix in {"xlsx", "xlsm"}:
+        return "xlsx"
+    if suffix in {"pptx"}:
+        return "pptx"
+    if suffix in {"drawio"}:
+        return "drawio"
+    if suffix in {"log", "txt"}:
+        return "log" if suffix == "log" else "other"
+    return "other"
+
+
+def normalize_capability_definition(
+    manifest: dict[str, Any],
+    *,
+    agent_id: str,
+    capability_path: Path | None = None,
+) -> dict[str, Any]:
+    execution = manifest.get("execution") if isinstance(manifest.get("execution"), dict) else {}
+    outputs = manifest.get("outputs") if isinstance(manifest.get("outputs"), dict) else {}
+    entrypoint = manifest.get("entrypoint") if isinstance(manifest.get("entrypoint"), dict) else {}
+    capability_id = str(manifest.get("id") or "")
+    short_id = capability_id.rsplit(".", 1)[-1] if capability_id else ""
+    return {
+        "id": capability_id,
+        "short_id": short_id,
+        "agent_id": agent_id,
+        "path": str(capability_path.resolve().relative_to(ROOT)) if capability_path else None,
+        "entrypoint": entrypoint,
+        "inputs": manifest.get("inputs") if isinstance(manifest.get("inputs"), dict) else {},
+        "outputs": {
+            **outputs,
+            "artifacts": normalize_capability_artifacts(outputs.get("artifacts")),
+        },
+        "requires": manifest.get("requires") if isinstance(manifest.get("requires"), dict) else {},
+        "runtime": manifest.get("runtime") if isinstance(manifest.get("runtime"), dict) else {},
+        "execution": {
+            "modes": list(execution.get("modes") or []),
+            "idempotency": execution.get("idempotency"),
+            "timeout_seconds": execution.get("timeout_seconds"),
+        },
+        "policy": capability_policy(manifest),
+    }
+
+
+def capability_request_metadata(request: CapabilityRunRequest) -> dict[str, Any]:
+    return {
+        "origin": request.origin,
+        "request_id": request.request_id,
+        "inputs": dict(request.inputs or {}),
+        "source_id": request.source_id,
+        "dry_run": request.dry_run,
+    }
+
+
+def structured_inputs_to_argv(request: CapabilityRunRequest) -> list[str]:
+    args = list(request.capability_args)
+    if request.source_id and "--source" not in args and not any(item.startswith("--source=") for item in args):
+        args.extend(["--source", request.source_id])
+    if request.dry_run and "--dry-run" not in args:
+        args.append("--dry-run")
+    return args

package/runtime/cli/aikit/core/requests.py

@@ -0,0 +1,69 @@
+"""Structured requests for reusable Agent DevKit core calls."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Iterable
+
+
+CAPABILITY_RUN_ORIGINS = {"cli", "mcp", "scheduler", "agent-prompt", "core"}
+
+
+@dataclass(frozen=True)
+class AgentPromptRequest:
+    prompt: str
+    llm: str | None = None
+    dry_run: bool = False
+    session_id: str | None = None
+    new_session: bool = False
+    no_llm_fallback: bool = False
+    prog_name: str = "agent"
+    project: str | None = None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.prompt, str):
+            raise ValueError("AgentPromptRequest.prompt must be a string")
+        if not isinstance(self.prog_name, str) or not self.prog_name.strip():
+            raise ValueError("AgentPromptRequest.prog_name must be a non-empty string")
+
+
+@dataclass(frozen=True)
+class CapabilityRunRequest:
+    agent_id: str
+    capability_id: str
+    capability_args: Iterable[str] = ()
+    capture_output: bool = True
+    origin: str = "core"
+    request_id: str | None = None
+    inputs: dict[str, Any] | None = None
+    source_id: str | None = None
+    dry_run: bool = False
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.agent_id, str) or not self.agent_id.strip():
+            raise ValueError("CapabilityRunRequest.agent_id must be a non-empty string")
+        if not isinstance(self.capability_id, str) or not self.capability_id.strip():
+            raise ValueError("CapabilityRunRequest.capability_id must be a non-empty string")
+        if self.capability_args is None:
+            object.__setattr__(self, "capability_args", ())
+        elif isinstance(self.capability_args, str):
+            raise ValueError("CapabilityRunRequest.capability_args must be an iterable of strings, not a string")
+        args = tuple(self.capability_args)
+        if not all(isinstance(item, str) for item in args):
+            raise ValueError("CapabilityRunRequest.capability_args must contain only strings")
+        object.__setattr__(self, "capability_args", args)
+        if not isinstance(self.capture_output, bool):
+            raise ValueError("CapabilityRunRequest.capture_output must be a boolean")
+        if self.origin not in CAPABILITY_RUN_ORIGINS:
+            allowed = ", ".join(sorted(CAPABILITY_RUN_ORIGINS))
+            raise ValueError(f"CapabilityRunRequest.origin must be one of: {allowed}")
+        if self.request_id is not None and not isinstance(self.request_id, str):
+            raise ValueError("CapabilityRunRequest.request_id must be a string when provided")
+        if self.source_id is not None and not isinstance(self.source_id, str):
+            raise ValueError("CapabilityRunRequest.source_id must be a string when provided")
+        if self.inputs is None:
+            object.__setattr__(self, "inputs", {})
+        elif not isinstance(self.inputs, dict):
+            raise ValueError("CapabilityRunRequest.inputs must be a mapping when provided")
+        if not isinstance(self.dry_run, bool):
+            raise ValueError("CapabilityRunRequest.dry_run must be a boolean")

package/runtime/cli/aikit/core/runtime.py

@@ -0,0 +1,64 @@
+"""Core runtime facade independent from CLI argument parsing."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cli.aikit.capability_runtime import (
+    list_agents,
+    list_all_capabilities,
+    list_capabilities,
+    load_agent,
+    load_capability,
+    run_capability,
+    summarize_agent,
+)
+from cli.aikit.core.capability_contract import structured_inputs_to_argv
+from cli.aikit.core.requests import AgentPromptRequest, CapabilityRunRequest
+from cli.aikit.natural_prompt_runtime import run_agent_prompt_request
+
+
+def run_agent_prompt(request: AgentPromptRequest) -> dict[str, Any]:
+    return run_agent_prompt_request(request)
+
+
+def list_agent_modules() -> dict[str, Any]:
+    return {"kind": "agents", "items": list_agents()}
+
+
+def list_capability_modules(agent_id: str | None = None) -> dict[str, Any]:
+    if agent_id:
+        agent = load_agent(agent_id)
+        return {
+            "kind": "capabilities",
+            "agent": agent["id"],
+            "items": list_capabilities(agent["path"]),
+        }
+    return {
+        "kind": "capabilities",
+        "agent": None,
+        "items": list_all_capabilities(),
+    }
+
+
+def inspect_capability_request(agent_id: str, capability_id: str) -> dict[str, Any]:
+    agent = load_agent(agent_id)
+    capability = load_capability(agent["path"], capability_id)
+    return {
+        "kind": "capability",
+        "agent": summarize_agent(agent),
+        "capability": capability,
+    }
+
+
+def run_capability_request(request: CapabilityRunRequest) -> dict[str, Any]:
+    agent = load_agent(request.agent_id)
+    return run_capability(
+        agent,
+        request.capability_id,
+        structured_inputs_to_argv(request),
+        capture_output=request.capture_output,
+        origin=request.origin,
+        request_id=request.request_id,
+        request_data=dict(request.inputs or {}),
+    )

package/runtime/cli/aikit/diagnostics.py

@@ -205,14 +205,17 @@ def claude_source(root: Path) -> dict[str, Any]:
     skill = plugin / "skills" / "ai-devkit-router" / "SKILL.md"
     commands = plugin / "commands"
     scripts = plugin / "scripts"
+    agents = plugin / "agents"
     return {
         "id": "claude-code",
         "path": str(plugin),
         "manifest_exists": manifest.exists(),
         "skill_exists": skill.exists(),
         "commands_exists": commands.is_dir(),
+        "agents_exists": agents.is_dir(),
+        "subagents": sorted(path.stem for path in agents.glob("*.md") if path.name != "README.md") if agents.is_dir() else [],
         "scripts_exists": scripts.is_dir(),
-        "status": "ok" if manifest.exists() and skill.exists() and commands.is_dir() and scripts.is_dir() else "error",
+        "status": "ok" if manifest.exists() and skill.exists() and commands.is_dir() and agents.is_dir() and scripts.is_dir() else "error",
     }
 
 
@@ -247,11 +250,14 @@ def installed_plugins(base: Path, lock: dict[str, Any]) -> dict[str, Any]:
         claude_plugin = base / ".claude" / "plugins" / "ai-devkit" / "plugin.json"
         claude_skill = base / ".claude" / "skills" / "ai-devkit-router" / "SKILL.md"
         claude_commands = base / ".claude" / "commands"
+        claude_agents = base / ".claude" / "plugins" / "ai-devkit" / "agents"
         status["claude-code"] = {
             "plugin_exists": claude_plugin.exists(),
             "skill_exists": claude_skill.exists(),
             "commands_exists": claude_commands.is_dir(),
-            "status": "ok" if claude_plugin.exists() and claude_skill.exists() and claude_commands.is_dir() else "missing",
+            "agents_exists": claude_agents.is_dir(),
+            "subagents": sorted(path.stem for path in claude_agents.glob("*.md") if path.name != "README.md") if claude_agents.is_dir() else [],
+            "status": "ok" if claude_plugin.exists() and claude_skill.exists() and claude_commands.is_dir() and claude_agents.is_dir() else "missing",
         }
     if "claude-desktop" in hosts:
         claude_desktop_plugin = base / ".claude" / "plugins" / "ai-devkit-skill" / "plugin.json"