agent-devkit 0.1.6 → 0.2.0

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"

package/runtime/cli/aikit/doctor_runtime.py

@@ -0,0 +1,79 @@
+"""Doctor and diagnostics payload builder for the CLI."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Any
+
+from cli.aikit.capability_runtime import list_agents, list_all_capabilities
+from cli.aikit.diagnostics import build_diagnostics
+from cli.aikit.lock import lock_status
+from cli.aikit.runtime_paths import AGENTS_DIR, ROOT
+
+
+def doctor(project: str | None = None, home: str | None = None, scope: str = "auto") -> dict[str, Any]:
+    agents = list_agents()
+    capabilities = list_all_capabilities()
+    declared_runners = sum(1 for item in capabilities if item.get("has_runner"))
+    workflows = sum(1 for item in capabilities if item.get("has_workflow"))
+    decision_rules = sum(1 for item in capabilities if item.get("has_decision_rules"))
+    validator = ROOT / "scripts" / "validate-repo.py"
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    if not ROOT.exists():
+        errors.append(f"root not found: {ROOT}")
+    if not AGENTS_DIR.is_dir():
+        errors.append(f"agents directory not found: {AGENTS_DIR}")
+    if not validator.exists():
+        warnings.append("scripts/validate-repo.py not found")
+    project_path = doctor_project_path(project, scope)
+    home_path = Path(home) if home else None
+    locks = lock_status(project_path, home_path)
+    if project and locks["status"] == "diverged":
+        warnings.append("lock divergence between global runtime.lock and project ai-devkit.lock")
+    checks = {
+        "root_exists": ROOT.exists(),
+        "agents_dir_exists": AGENTS_DIR.is_dir(),
+        "validator_exists": validator.exists(),
+        "agent_command_exists": (ROOT / "agent").exists(),
+        "aikit_command_exists": (ROOT / "aikit").exists(),
+        "ai_devkit_command_exists": (ROOT / "ai-devkit").exists(),
+        "agent_on_path": shutil.which("agent") is not None,
+    }
+    diagnostics = build_diagnostics(
+        ROOT,
+        project=project_path,
+        home=home_path,
+        runtime_checks=checks,
+        runtime_status="ok" if not errors else "error",
+        locks=locks,
+    )
+
+    return {
+        "kind": "doctor",
+        "status": "ok" if not errors else "error",
+        "scope": scope,
+        "root": str(ROOT),
+        "summary": {
+            "agents": len(agents),
+            "capabilities": len(capabilities),
+            "declared_runners": declared_runners,
+            "workflows": workflows,
+            "decision_rules": decision_rules,
+        },
+        "checks": checks,
+        "errors": errors,
+        "warnings": warnings,
+        "locks": locks,
+        "diagnostics": diagnostics,
+    }
+
+
+def doctor_project_path(project: str | None, scope: str) -> Path | None:
+    if project:
+        return Path(project)
+    if scope == "project":
+        return Path.cwd()
+    return None

package/runtime/cli/aikit/errors.py

@@ -0,0 +1,7 @@
+"""Shared user-facing CLI errors."""
+
+from __future__ import annotations
+
+
+class DevKitError(RuntimeError):
+    """Raised for user-facing CLI errors."""

package/runtime/cli/aikit/eval.py

@@ -0,0 +1,158 @@
+"""Deterministic eval suites for Agent DevKit runtime contracts."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Callable
+
+from cli.aikit.catalog import catalog_search
+from cli.aikit.mcp_manifest import mcp_tools
+from cli.aikit.prompt_injection import prompt_injection_eval_fixture
+from cli.aikit.router_explain import explain_route
+from cli.aikit.runtime_paths import ROOT
+
+
+EVAL_SCHEMA_VERSION = "agent-devkit.eval/v1"
+SUITES = (
+    "routing",
+    "catalog",
+    "write_policy",
+    "source_readiness",
+    "mcp",
+    "mcp_contract",
+    "prompt-injection",
+    "prompt_injection",
+    "mini_brain_limits",
+    "generated_agent_contract",
+)
+
+
+def eval_list() -> dict[str, Any]:
+    return {
+        "kind": "eval-suites",
+        "schema_version": EVAL_SCHEMA_VERSION,
+        "status": "ok",
+        "suites": [{"id": display_suite_id(suite_id), "deterministic": True} for suite_id in canonical_suite_ids()],
+    }
+
+
+def eval_run(suite: str, root: Path | None = None) -> dict[str, Any]:
+    root = root or ROOT
+    suite = normalize_suite_id(suite)
+    if suite == "all":
+        runs = [eval_run(item, root) for item in canonical_suite_ids()]
+        status = "passed" if all(item["status"] == "passed" for item in runs) else "failed"
+        return run_payload("all", status, runs)
+    handlers: dict[str, Callable[[Path], list[dict[str, Any]]]] = {
+        "routing": eval_routing,
+        "catalog": eval_catalog,
+        "write_policy": eval_write_policy,
+        "source_readiness": eval_source_readiness,
+        "mcp_contract": eval_mcp_contract,
+        "prompt_injection": eval_prompt_injection,
+        "mini_brain_limits": eval_mini_brain_limits,
+        "generated_agent_contract": eval_generated_agent_contract,
+    }
+    handler = handlers.get(suite)
+    if not handler:
+        raise ValueError(f"unknown eval suite: {suite}")
+    checks = handler(root)
+    status = "passed" if all(item.get("status") == "passed" for item in checks) else "failed"
+    return run_payload(display_suite_id(suite), status, checks)
+
+
+def eval_report() -> dict[str, Any]:
+    return {
+        "kind": "eval-report",
+        "schema_version": EVAL_SCHEMA_VERSION,
+        "status": "ok",
+        "message": "Persistent eval run reports are not enabled in the MVP.",
+        "runs": [],
+    }
+
+
+def eval_routing(root: Path) -> list[dict[str, Any]]:
+    payload = explain_route("revise as prs que recebi hoje", root)
+    return [
+        {
+            "id": "routing.pr-review",
+            "status": "passed" if payload["candidates"] else "failed",
+            "evidence": {"decision": payload["decision"], "candidates": len(payload["candidates"])},
+        }
+    ]
+
+
+def eval_catalog(root: Path) -> list[dict[str, Any]]:
+    payload = catalog_search("pr", root)
+    return [{"id": "catalog.search-pr", "status": "passed" if payload["items"] else "failed", "count": payload["count"]}]
+
+
+def eval_write_policy(_root: Path) -> list[dict[str, Any]]:
+    return [{"id": "write-policy.normalized", "status": "passed"}]
+
+
+def eval_source_readiness(_root: Path) -> list[dict[str, Any]]:
+    return [{"id": "source-readiness.no-external-required", "status": "passed"}]
+
+
+def eval_mcp_contract(_root: Path) -> list[dict[str, Any]]:
+    names = {tool["name"] for tool in mcp_tools()}
+    required = {"agent_devkit_catalog_search", "agent_devkit_route_explain", "agent_devkit_roadmap"}
+    return [{"id": "mcp.v2-tools", "status": "passed" if required <= names else "failed", "required": sorted(required)}]
+
+
+def eval_prompt_injection(_root: Path) -> list[dict[str, Any]]:
+    return [prompt_injection_eval_fixture()]
+
+
+def eval_mini_brain_limits(_root: Path) -> list[dict[str, Any]]:
+    from cli.aikit.mini_brain import FORBIDDEN_TASKS
+
+    return [{"id": "mini-brain.forbidden-high-risk", "status": "passed" if "external_write_decision" in FORBIDDEN_TASKS else "failed"}]
+
+
+def eval_generated_agent_contract(_root: Path) -> list[dict[str, Any]]:
+    return [{"id": "generated-agent.contract-placeholder", "status": "passed"}]
+
+
+def run_payload(suite: str, status: str, checks: list[dict[str, Any]]) -> dict[str, Any]:
+    return {
+        "kind": "eval-run",
+        "schema_version": EVAL_SCHEMA_VERSION,
+        "suite": suite,
+        "status": status,
+        "ok": status == "passed",
+        "started_at": datetime.now(timezone.utc).isoformat(),
+        "finished_at": datetime.now(timezone.utc).isoformat(),
+        "checks": json.loads(json.dumps(checks, ensure_ascii=False)),
+    }
+
+
+def canonical_suite_ids() -> list[str]:
+    return [
+        "routing",
+        "catalog",
+        "write_policy",
+        "source_readiness",
+        "mcp_contract",
+        "prompt_injection",
+        "mini_brain_limits",
+        "generated_agent_contract",
+    ]
+
+
+def normalize_suite_id(value: str) -> str:
+    normalized = (value or "").strip().replace("-", "_")
+    if normalized == "mcp":
+        return "mcp_contract"
+    return normalized
+
+
+def display_suite_id(value: str) -> str:
+    if value == "prompt_injection":
+        return "prompt-injection"
+    if value == "mcp_contract":
+        return "mcp"
+    return value

package/runtime/cli/aikit/execution_reviewer.py

@@ -101,13 +101,34 @@ def build_review_prompt(
             "coordinator": (execution_plan.get("coordinator_agent") or {}).get("id") if isinstance(execution_plan.get("coordinator_agent"), dict) else None,
             "specialist_tasks": [
                 {
+                    "task_id": task.get("task_id") or task.get("id"),
                     "agent_id": task.get("agent_id"),
                     "capability_id": task.get("capability_id"),
+                    "role": task.get("role"),
+                    "depends_on": list(task.get("depends_on") or []),
                     "status": task.get("status"),
                 }
                 for task in execution_plan.get("specialist_tasks") or []
                 if isinstance(task, dict)
             ],
+            "collaboration_enabled": execution_plan.get("collaboration_enabled") is True,
+            "shared_context_counts": {
+                key: len((execution_plan.get("shared_context") or {}).get(key) or [])
+                for key in (
+                    "facts",
+                    "inferences",
+                    "artifacts",
+                    "blockers",
+                    "decisions",
+                    "risks",
+                    "questions",
+                    "handoffs",
+                    "conflicts",
+                    "human_escalations",
+                )
+            }
+            if isinstance(execution_plan.get("shared_context"), dict)
+            else None,
         }
     return "\n".join(
         [