agent-devkit 0.1.0 → 0.1.6

package/runtime/cli/aikit/agent_executor.py

@@ -0,0 +1,66 @@
+"""Execution helpers for multi-agent plans."""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+
+RunCapability = Callable[[dict[str, Any], str, list[str]], dict[str, Any]]
+LoadAgent = Callable[[str], dict[str, Any]]
+
+
+def execute_plan_tasks(
+    plan: dict[str, Any],
+    *,
+    load_agent: LoadAgent,
+    run_capability: RunCapability,
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    executed: list[dict[str, Any]] = []
+    blocked: list[dict[str, Any]] = []
+    for task in plan.get("specialist_tasks") or []:
+        if not task.get("primary"):
+            continue
+        if not task.get("executable"):
+            blocked.append(blocked_task(task, "Capability has no executable runner."))
+            continue
+        if str(task.get("write_policy") or "") not in {"read_only", "dry_run"}:
+            blocked.append(blocked_task(task, "Capability requires explicit confirmation for external write effects."))
+            continue
+        try:
+            agent = load_agent(str(task["agent_id"]))
+            result = run_capability(agent, str(task["capability_id"]), list(task.get("args") or []))
+        except Exception as exc:  # pragma: no cover - converted to user-facing payload.
+            blocked.append(blocked_task(task, str(exc)))
+            continue
+        item = public_task_result(task, result)
+        if result.get("ok"):
+            executed.append(item)
+        else:
+            blocked.append(item)
+    return executed, blocked
+
+
+def public_task_result(task: dict[str, Any], result: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "id": task.get("id"),
+        "agent_id": task.get("agent_id"),
+        "capability_id": task.get("capability_id"),
+        "status": result.get("status"),
+        "ok": bool(result.get("ok")),
+        "provider": task.get("provider"),
+        "write_policy": task.get("write_policy"),
+        "result": result,
+    }
+
+
+def blocked_task(task: dict[str, Any], reason: str) -> dict[str, Any]:
+    return {
+        "id": task.get("id"),
+        "agent_id": task.get("agent_id"),
+        "capability_id": task.get("capability_id"),
+        "status": "blocked",
+        "ok": False,
+        "provider": task.get("provider"),
+        "write_policy": task.get("write_policy"),
+        "reason": reason,
+    }

package/runtime/cli/aikit/agent_registry.py

@@ -0,0 +1,80 @@
+"""Agent and capability registry helpers for orchestration."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def load_agent_registry(root: Path) -> dict[str, Any]:
+    agents_dir = root / "agents"
+    agents: dict[str, dict[str, Any]] = {}
+    capabilities: dict[str, dict[str, Any]] = {}
+    if not agents_dir.exists():
+        return {"agents": agents, "capabilities": capabilities}
+    for agent_path in sorted(path for path in agents_dir.iterdir() if path.is_dir()):
+        manifest_path = agent_path / "agent.yaml"
+        if not manifest_path.exists():
+            continue
+        agent = read_yaml(manifest_path)
+        agent_id = str(agent.get("id") or agent_path.name)
+        agent["id"] = agent_id
+        agent["path"] = str(agent_path.relative_to(root))
+        agent["capabilities_index"] = {}
+        for capability_path in sorted((agent_path / "capabilities").glob("*/capability.yaml")):
+            capability = read_yaml(capability_path)
+            capability_id = str(capability.get("id") or capability_path.parent.name)
+            short_id = capability_id.rsplit(".", 1)[-1]
+            public_capability = {
+                "id": capability_id,
+                "short_id": short_id,
+                "agent_id": agent_id,
+                "name": capability.get("name") or short_id,
+                "purpose": compact(str(capability.get("purpose") or "")),
+                "write_policy": capability.get("write_policy"),
+                "inputs": capability.get("inputs") or {},
+                "outputs": capability.get("outputs") or {},
+                "integration": capability.get("integration") or {},
+                "requires": capability.get("requires") or {},
+                "has_runner": bool(((capability.get("entrypoint") or {}).get("runner"))),
+                "path": str(capability_path.parent.relative_to(root)),
+            }
+            agent["capabilities_index"][short_id] = public_capability
+            capabilities[f"{agent_id}/{short_id}"] = public_capability
+        agents[agent_id] = public_agent(agent)
+    return {"agents": agents, "capabilities": capabilities}
+
+
+def public_agent(agent: dict[str, Any]) -> dict[str, Any]:
+    surface = agent.get("agent_surface") if isinstance(agent.get("agent_surface"), dict) else {}
+    return {
+        "id": agent.get("id"),
+        "name": agent.get("name") or agent.get("id"),
+        "kind": agent.get("kind"),
+        "status": agent.get("status"),
+        "purpose": compact(str(agent.get("purpose") or "")),
+        "depends_on_agents": list(agent.get("depends_on_agents") or []),
+        "orchestrated_agents": list(surface.get("orchestrated_agents") or []),
+        "capabilities": list(agent.get("capabilities") or []),
+        "capabilities_index": dict(agent.get("capabilities_index") or {}),
+        "write_policy": agent.get("write_policy"),
+        "path": agent.get("path"),
+    }
+
+
+def find_capability(registry: dict[str, Any], agent_id: str, capability_id: str) -> dict[str, Any] | None:
+    return (registry.get("capabilities") or {}).get(f"{agent_id}/{capability_id}")
+
+
+def read_yaml(path: Path) -> dict[str, Any]:
+    data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    return data if isinstance(data, dict) else {}
+
+
+def compact(value: str, *, limit: int = 240) -> str:
+    text = " ".join(value.split())
+    if len(text) <= limit:
+        return text
+    return text[: limit - 3].rstrip() + "..."

package/runtime/cli/aikit/app_home.py

@@ -3,12 +3,16 @@
 from __future__ import annotations
 
 import os
+import shutil
 from pathlib import Path
+from typing import Any
 
 
+CANONICAL_APP_HOME_ENV = "AGENT_DEVKIT_HOME"
 APP_HOME_ENV = "AI_DEVKIT_CONFIG_HOME"
 LEGACY_APP_HOME_ENV = "AIKIT_CONFIG_HOME"
-DEFAULT_APP_HOME_NAME = ".ai-devkit"
+DEFAULT_APP_HOME_NAME = ".agent-devkit"
+LEGACY_DEFAULT_APP_HOME_NAME = ".ai-devkit"
 
 APP_DIRS = (
     "bin",
@@ -27,12 +31,93 @@ APP_DIRS = (
 
 def app_home() -> Path:
     """Return the configured Agent DevKit home directory."""
-    raw = os.environ.get(APP_HOME_ENV) or os.environ.get(LEGACY_APP_HOME_ENV)
+    raw = os.environ.get(CANONICAL_APP_HOME_ENV) or os.environ.get(APP_HOME_ENV) or os.environ.get(LEGACY_APP_HOME_ENV)
     if raw:
         return Path(raw).expanduser().resolve()
+    canonical = canonical_default_app_home()
+    legacy = legacy_default_app_home()
+    if canonical.exists():
+        return canonical
+    if legacy.exists():
+        return legacy
+    return canonical
+
+
+def canonical_default_app_home() -> Path:
     return (Path.home() / DEFAULT_APP_HOME_NAME).resolve()
 
 
+def legacy_default_app_home() -> Path:
+    return (Path.home() / LEGACY_DEFAULT_APP_HOME_NAME).resolve()
+
+
+def app_home_status() -> dict[str, Any]:
+    explicit_env = active_home_env()
+    canonical = canonical_default_app_home()
+    legacy = legacy_default_app_home()
+    home = app_home()
+    status = "canonical"
+    if explicit_env:
+        status = "env"
+    elif home == legacy:
+        status = "legacy-default-detected"
+    elif not canonical.exists() and not legacy.exists():
+        status = "canonical-default"
+    return {
+        "kind": "app-home-status",
+        "status": status,
+        "home": str(home),
+        "canonical_home": str(canonical),
+        "legacy_home": str(legacy),
+        "active_env": explicit_env,
+        "canonical_exists": canonical.exists(),
+        "legacy_exists": legacy.exists(),
+        "migration_available": not explicit_env and legacy.exists() and not canonical.exists(),
+        "migration_command": "agent config migrate-home",
+    }
+
+
+def active_home_env() -> dict[str, str] | None:
+    for name in (CANONICAL_APP_HOME_ENV, APP_HOME_ENV, LEGACY_APP_HOME_ENV):
+        value = os.environ.get(name)
+        if value:
+            return {"name": name, "value": str(Path(value).expanduser().resolve())}
+    return None
+
+
+def migrate_default_home(*, dry_run: bool = False) -> dict[str, Any]:
+    source = legacy_default_app_home()
+    destination = canonical_default_app_home()
+    payload: dict[str, Any] = {
+        "kind": "home-migration",
+        "source": str(source),
+        "destination": str(destination),
+        "dry_run": dry_run,
+        "executed": False,
+    }
+    if destination.exists():
+        return {**payload, "status": "not-needed", "message": "Canonical Agent DevKit home already exists."}
+    if not source.exists():
+        return {**payload, "status": "not-needed", "message": "Legacy AI DevKit home was not found."}
+    if dry_run:
+        return {**payload, "status": "planned", "message": "Legacy home would be migrated to canonical Agent DevKit home."}
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        source.rename(destination)
+        method = "rename"
+    except OSError:
+        shutil.copytree(source, destination)
+        shutil.rmtree(source)
+        method = "copytree"
+    return {
+        **payload,
+        "status": "migrated",
+        "executed": True,
+        "method": method,
+        "message": "Legacy home migrated to canonical Agent DevKit home.",
+    }
+
+
 def app_path(*parts: str) -> Path:
     return app_home().joinpath(*parts)
 

package/runtime/cli/aikit/audit.py

@@ -60,6 +60,7 @@ def record_audit(
         "prompt_normalized": normalize_prompt(prompt) if prompt else None,
         "session": extract_session(safe_result),
         "route": safe_result.get("route"),
+        "orchestration": extract_orchestration(safe_result),
         "agent": extract_agent(safe_result, args),
         "providers": extract_providers(safe_result),
         "sources": extract_sources(safe_result),
@@ -282,6 +283,43 @@ def extract_external_actions(result: dict[str, Any]) -> list[dict[str, Any]]:
     return actions
 
 
+def extract_orchestration(result: dict[str, Any]) -> dict[str, Any] | None:
+    plan = result.get("execution_plan")
+    if not isinstance(plan, dict):
+        return None
+    return {
+        "kind": plan.get("kind"),
+        "status": plan.get("status"),
+        "coordinator_agent": (plan.get("coordinator_agent") or {}).get("id") if isinstance(plan.get("coordinator_agent"), dict) else None,
+        "domain_agent": (plan.get("domain_agent") or {}).get("id") if isinstance(plan.get("domain_agent"), dict) else None,
+        "specialist_tasks": [
+            {
+                "agent_id": task.get("agent_id"),
+                "capability_id": task.get("capability_id"),
+                "status": task.get("status"),
+            }
+            for task in plan.get("specialist_tasks") or []
+            if isinstance(task, dict)
+        ],
+        "configuration_tasks": [
+            {
+                "agent_id": task.get("agent_id"),
+                "provider": task.get("provider"),
+                "status": task.get("status"),
+            }
+            for task in plan.get("configuration_tasks") or []
+            if isinstance(task, dict)
+        ],
+        "review_task": {
+            "agent_id": (plan.get("review_task") or {}).get("agent_id"),
+            "status": (plan.get("review_task") or {}).get("status"),
+        }
+        if isinstance(plan.get("review_task"), dict)
+        else None,
+        "trace": result.get("orchestration_trace") or plan.get("trace") or [],
+    }
+
+
 def summarize_result(result: dict[str, Any]) -> dict[str, Any]:
     return {
         "kind": result.get("kind"),
@@ -326,6 +364,12 @@ def render_audit_md(entry: dict[str, Any]) -> str:
         json.dumps(entry.get("providers") or {}, ensure_ascii=False, indent=2, sort_keys=True),
         "```",
         "",
+        "## Orchestration",
+        "",
+        "```json",
+        json.dumps(entry.get("orchestration") or {}, ensure_ascii=False, indent=2, sort_keys=True),
+        "```",
+        "",
         "## Permissions",
         "",
         "```json",

package/runtime/cli/aikit/configuration_orchestrator.py

@@ -0,0 +1,291 @@
+"""Global configuration orchestration for missing providers and sources."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from cli.aikit.decision_store import is_disabled
+from cli.aikit.providers import ProviderRegistryError, load_providers, provider_or_error
+
+
+PROJECT_PATTERN = re.compile(r"(?i)\bprojeto\s+([A-Za-z0-9._ -]{2,80}?)(?:\s+no\b|\s+na\b|\s+do\b|\s+da\b|$)")
+
+
+def provider_setup_wizard(
+    root: Path,
+    provider_id: str,
+    *,
+    prompt: str | None = None,
+    route: dict[str, Any] | None = None,
+    agent_id: str | None = None,
+    capability_id: str | None = None,
+    reason: str | None = None,
+) -> dict[str, Any]:
+    provider = load_provider(root, provider_id)
+    provider_name = str(provider.get("name") or provider_id)
+    intent = str((route or {}).get("intent") or capability_id or "provider-configuration")
+    suggested_project = infer_project(prompt or "")
+    source_context = bool(route and route.get("intent"))
+    suggested_source_id = suggest_source_id(provider_id, suggested_project)
+    disabled = is_disabled("tools", provider_id) or is_disabled("integrations", provider_id)
+    questions = build_questions(provider, suggested_project=suggested_project, suggested_source_id=suggested_source_id, include_source=source_context)
+    next_question = disabled_notice(provider_id, provider_name) if disabled else opt_in_question(provider_id, provider_name)
+    return {
+        "kind": "provider-setup-wizard",
+        "status": "denied-by-user" if disabled else "waiting-for-user",
+        "provider": provider_id,
+        "provider_name": provider_name,
+        "provider_kind": provider.get("kind"),
+        "intent": intent,
+        "agent_id": agent_id or (route or {}).get("agent_id"),
+        "capability_id": capability_id or (route or {}).get("capability_id"),
+        "reason": reason,
+        "resume_prompt": prompt,
+        "suggested_source_id": suggested_source_id if source_context else None,
+        "suggested_config": suggested_config(provider_id, suggested_project),
+        "next_question": next_question,
+        "questions": questions,
+        "credential_options": credential_options(provider),
+        "config_fields": public_config_fields(provider),
+        "auth_methods": public_auth_methods(provider),
+        "fallbacks": list(provider.get("fallbacks", []) or []),
+        "stores_secret": False,
+        "owner_agent": "provider-configurator",
+        "message": (
+            f"{provider_name} esta desativado. O agente seguira sem essa ferramenta ate voce reativar."
+            if disabled
+            else f"Para continuar, o agente precisa configurar ou autorizar {provider_name}."
+        ),
+    }
+
+
+def provider_wizard_from_requirement(
+    root: Path,
+    provider_id: str,
+    *,
+    agent_id: str | None = None,
+    capability_id: str | None = None,
+    reason: str | None = None,
+) -> dict[str, Any]:
+    return provider_setup_wizard(
+        root,
+        provider_id,
+        agent_id=agent_id,
+        capability_id=capability_id,
+        reason=reason or "Capability provider requirement is not configured.",
+    )
+
+
+def load_provider(root: Path, provider_id: str) -> dict[str, Any]:
+    try:
+        return provider_or_error(load_providers(root), provider_id)
+    except ProviderRegistryError:
+        return {
+            "id": provider_id,
+            "name": provider_id,
+            "kind": "unknown",
+            "config_fields": [],
+            "auth_methods": [],
+            "fallbacks": [],
+        }
+
+
+def build_questions(
+    provider: dict[str, Any],
+    *,
+    suggested_project: str | None,
+    suggested_source_id: str,
+    include_source: bool,
+) -> list[dict[str, Any]]:
+    questions: list[dict[str, Any]] = []
+    for field in provider.get("config_fields", []) or []:
+        if not isinstance(field, dict):
+            continue
+        name = str(field.get("name") or "").strip()
+        if not name:
+            continue
+        suggested_value = suggested_value_for_field(provider, name, suggested_project)
+        questions.append(
+            {
+                "id": field_question_id(provider["id"], name),
+                "type": "text",
+                "text": question_text(provider, name, suggested_value=suggested_value),
+                "config_key": name,
+                "env": name,
+                "required": bool(field.get("required")),
+                "secret": bool(field.get("secret")),
+                "default": field.get("default"),
+                "suggested_value": suggested_value,
+            }
+        )
+    auth_methods = public_auth_methods(provider)
+    if auth_methods:
+        questions.append(
+            {
+                "id": f"{provider_slug(str(provider['id']))}_auth",
+                "type": "select",
+                "text": "Como deseja autenticar?",
+                "options": [method["id"] for method in auth_methods] + ["env", "file", "skip"],
+                "auth_methods": auth_methods,
+            }
+        )
+    if include_source:
+        questions.append(
+            {
+                "id": "source_id",
+                "type": "text",
+                "text": "Qual nome local deseja dar para esta fonte?",
+                "suggested_value": suggested_source_id,
+            }
+        )
+        questions.append(
+            {
+                "id": "default_for_intent",
+                "type": "confirm",
+                "text": "Posso usar esta fonte como padrao para este tipo de pedido?",
+                "default": True,
+            }
+        )
+    if not questions:
+        questions.append(
+            {
+                "id": f"{provider_slug(str(provider['id']))}_confirm",
+                "type": "confirm",
+                "text": f"Posso tentar usar {provider.get('name') or provider['id']} com a cadeia de credenciais nativa?",
+                "default": False,
+            }
+        )
+    return questions
+
+
+def opt_in_question(provider_id: str, provider_name: str) -> dict[str, Any]:
+    return {
+        "id": f"{provider_slug(provider_id)}_opt_in",
+        "type": "confirm",
+        "text": f"Posso configurar ou autorizar {provider_name} para atender este pedido?",
+        "default": False,
+    }
+
+
+def disabled_notice(provider_id: str, provider_name: str) -> dict[str, Any]:
+    return {
+        "id": f"{provider_slug(provider_id)}_disabled",
+        "type": "notice",
+        "text": f"{provider_name} esta desativado por decisao do usuario. Reative para usar esta integracao.",
+        "default": False,
+    }
+
+
+def public_config_fields(provider: dict[str, Any]) -> list[dict[str, Any]]:
+    fields = []
+    for field in provider.get("config_fields", []) or []:
+        if not isinstance(field, dict):
+            continue
+        fields.append(
+            {
+                "name": field.get("name"),
+                "required": bool(field.get("required")),
+                "secret": bool(field.get("secret")),
+                "default": field.get("default"),
+            }
+        )
+    return fields
+
+
+def public_auth_methods(provider: dict[str, Any]) -> list[dict[str, Any]]:
+    methods = []
+    for method in provider.get("auth_methods", []) or []:
+        if not isinstance(method, dict):
+            continue
+        methods.append(
+            {
+                "id": method.get("id"),
+                "label": method.get("label") or method.get("id"),
+                "native": bool(method.get("native")),
+                "config_fields": list(method.get("config_fields", []) or []),
+                "secret_fields": list(method.get("secret_fields", []) or []),
+            }
+        )
+    return methods
+
+
+def credential_options(provider: dict[str, Any]) -> list[dict[str, Any]]:
+    options = []
+    for method in public_auth_methods(provider):
+        for secret_field in method.get("secret_fields") or []:
+            options.append(
+                {
+                    "id": f"env:{secret_field}",
+                    "label": f"Variavel de ambiente {secret_field}",
+                    "env": secret_field,
+                    "auth_method": method.get("id"),
+                    "stores_secret": False,
+                }
+            )
+    options.extend(
+        [
+            {"id": "file", "label": "Arquivo local de credencial", "stores_secret": False},
+            {"id": "native", "label": "Cadeia nativa ou CLI ja autenticada", "stores_secret": False},
+            {"id": "skip", "label": "Ignorar esta ferramenta", "stores_secret": False},
+        ]
+    )
+    seen: set[str] = set()
+    unique = []
+    for option in options:
+        option_id = str(option.get("id"))
+        if option_id not in seen:
+            seen.add(option_id)
+            unique.append(option)
+    return unique
+
+
+def suggested_config(provider_id: str, suggested_project: str | None) -> dict[str, Any]:
+    config: dict[str, Any] = {}
+    if provider_id == "azure-devops" and suggested_project:
+        config["project"] = suggested_project
+        config["AZURE_DEVOPS_PROJECT"] = suggested_project
+    return config
+
+
+def suggested_value_for_field(provider: dict[str, Any], name: str, suggested_project: str | None) -> str | None:
+    if provider.get("id") == "azure-devops" and name == "AZURE_DEVOPS_PROJECT" and suggested_project:
+        return suggested_project
+    return None
+
+
+def question_text(provider: dict[str, Any], name: str, *, suggested_value: str | None) -> str:
+    if provider.get("id") == "azure-devops" and name == "AZURE_DEVOPS_ORG":
+        return "Qual e a organizacao do Azure DevOps?"
+    if provider.get("id") == "azure-devops" and name == "AZURE_DEVOPS_PROJECT":
+        if suggested_value:
+            return f'O projeto e "{suggested_value}"? Se nao, informe o nome correto.'
+        return "Qual e o nome do projeto no Azure DevOps?"
+    label = name.replace("_", " ").lower()
+    return f"Informe {label} para {provider.get('name') or provider.get('id')}."
+
+
+def field_question_id(provider_id: str, name: str) -> str:
+    return f"{provider_slug(provider_id)}_{provider_slug(name)}"
+
+
+def infer_project(prompt: str) -> str | None:
+    match = PROJECT_PATTERN.search(prompt)
+    if not match:
+        return None
+    project = " ".join(match.group(1).strip(" .,_-").split())
+    return project or None
+
+
+def suggest_source_id(provider: str, project: str | None) -> str:
+    parts = [provider]
+    if project:
+        parts.append(project)
+    raw = "-".join(parts)
+    normalized = re.sub(r"[^a-z0-9._-]+", "-", raw.lower()).strip("-")
+    return normalized or provider_slug(provider)
+
+
+def provider_slug(provider: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "_", provider.lower()).strip("_") or "provider"