agent-devkit 0.1.5 → 0.1.6

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/control_router.py

@@ -0,0 +1,298 @@
+"""Natural-language control routing for tools, integrations, skills and LLMs."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from cli.aikit.decision_store import forget_decision, list_decisions, reset_decisions, set_decision
+from cli.aikit.llm import BACKENDS
+from cli.aikit.providers import load_providers
+from cli.aikit.toolchain import load_toolchain
+
+
+CATEGORY_ALIASES: dict[str, tuple[str, ...]] = {
+    "tools": ("tool", "tools", "ferramenta", "ferramentas", "cli", "clis", "toolchain"),
+    "integrations": ("integration", "integrations", "integracao", "integracoes", "integração", "integrações", "provider", "providers"),
+    "skills": ("skill", "skills", "habilidade", "habilidades"),
+    "llms": ("llm", "llms", "modelo", "modelos", "backend", "backends"),
+}
+LIST_MARKERS = ("mostre", "mostrar", "liste", "listar", "ver", "exiba", "exibir")
+ENABLE_MARKERS = ("reative", "ative", "habilite", "enable")
+DISABLE_MARKERS = ("desative", "desabilite", "disable", "bloqueie", "bloquear")
+FORGET_MARKERS = ("esqueca", "esqueça", "remova", "remover", "limpe", "limpar", "delete", "apague", "apagar")
+DECISION_MARKERS = ("decisao", "decisão", "decisoes", "decisões", "decision", "decisions", "bloqueio")
+TOKEN_PATTERN = re.compile(r"[a-z0-9._:-]+")
+SKILL_ROW_PATTERN = re.compile(r"^\|\s*`([^`]+)`\s*\|")
+
+
+def dispatch_natural_control_prompt(root: Path, normalized_prompt: str) -> dict[str, Any] | None:
+    action = detect_action(normalized_prompt)
+    category = detect_category(normalized_prompt)
+    if action == "list":
+        return list_payload(root, category=category)
+    if action == "reset" and category:
+        result = reset_decisions(category)
+        return control_payload(
+            status="ok",
+            response=f"Decisoes de {category} foram resetadas.",
+            result={"action": "reset", "category": category, "decision": result},
+        )
+    if action not in {"enable", "disable", "forget"}:
+        return None
+
+    index = build_control_index(root)
+    matches = resolve_target(index, normalized_prompt, category=category)
+    if not matches:
+        return needs_input_unknown(root, normalized_prompt, category=category)
+    if len(matches) > 1:
+        return needs_input_ambiguous(matches, normalized_prompt, category=category)
+
+    target = matches[0]
+    if action == "forget":
+        decision = forget_decision(str(target["category"]), str(target["id"]))
+        return control_payload(
+            status="ok",
+            response=f"Decisao local sobre {target['id']} removida.",
+            result={"action": "forget", "category": target["category"], "id": target["id"], "removed": decision.get("removed"), "decision": decision},
+        )
+
+    state = "enabled" if action == "enable" else "disabled_by_user"
+    decision = set_decision(str(target["category"]), str(target["id"]), state, reason=f"natural prompt: {action}")
+    return control_payload(
+        status="ok",
+        response=f"{target['id']} foi {'ativado' if state == 'enabled' else 'desativado'} para {target['category']}.",
+        result={"action": action, "category": target["category"], "id": target["id"], "state": state, "decision": decision.get("item")},
+    )
+
+
+def plan_natural_control_prompt(root: Path, normalized_prompt: str) -> dict[str, Any] | None:
+    action = detect_action(normalized_prompt)
+    category = detect_category(normalized_prompt)
+    if action == "list":
+        payload = list_payload(root, category=category)
+        payload["dry_run"] = True
+        return payload
+    if action == "reset" and category:
+        return control_payload(
+            status="planned",
+            response=f"Dry-run: decisoes de {category} seriam resetadas.",
+            result={"action": "reset", "category": category},
+        ) | {"dry_run": True, "ok": True}
+    if action not in {"enable", "disable", "forget"}:
+        return None
+    index = build_control_index(root)
+    matches = resolve_target(index, normalized_prompt, category=category)
+    if not matches:
+        payload = needs_input_unknown(root, normalized_prompt, category=category)
+        payload["dry_run"] = True
+        return payload
+    if len(matches) > 1:
+        payload = needs_input_ambiguous(matches, normalized_prompt, category=category)
+        payload["dry_run"] = True
+        return payload
+    target = matches[0]
+    state = "enabled" if action == "enable" else "disabled_by_user"
+    return control_payload(
+        status="planned",
+        response=f"Dry-run: {target['id']} seria {'ativado' if action == 'enable' else 'desativado' if action == 'disable' else 'removido das decisoes'} para {target['category']}.",
+        result={"action": action, "category": target["category"], "id": target["id"], "state": state if action != "forget" else None},
+    ) | {"dry_run": True, "ok": True}
+
+
+def build_control_index(root: Path) -> dict[str, list[dict[str, Any]]]:
+    return {
+        "tools": tool_items(root),
+        "integrations": integration_items(root),
+        "skills": skill_items(root),
+        "llms": llm_items(),
+    }
+
+
+def tool_items(root: Path) -> list[dict[str, Any]]:
+    return [
+        item("tools", tool_id, label=str(spec.get("label") or tool_id), source="toolchain", aliases=aliases_for(tool_id, spec.get("label")))
+        for tool_id, spec in load_toolchain(root).items()
+    ]
+
+
+def integration_items(root: Path) -> list[dict[str, Any]]:
+    items = []
+    for provider in load_providers(root):
+        provider_id = str(provider.get("id") or "")
+        if provider_id:
+            items.append(item("integrations", provider_id, label=str(provider.get("name") or provider_id), source="providers", aliases=aliases_for(provider_id, provider.get("name"))))
+    return items
+
+
+def skill_items(root: Path) -> list[dict[str, Any]]:
+    catalog = root / "vendor" / "skills" / "CATALOG.md"
+    if not catalog.exists():
+        return []
+    items = []
+    for line in catalog.read_text(encoding="utf-8").splitlines():
+        match = SKILL_ROW_PATTERN.match(line)
+        if not match:
+            continue
+        skill_id = match.group(1).strip()
+        if skill_id and skill_id.lower() != "skill":
+            items.append(item("skills", skill_id, label=skill_id, source="vendor-skills", aliases=aliases_for(skill_id)))
+    return items
+
+
+def llm_items() -> list[dict[str, Any]]:
+    return [
+        item("llms", backend_id, label=backend.display_name, source="llm-backends", aliases=aliases_for(backend_id, backend.display_name))
+        for backend_id, backend in BACKENDS.items()
+    ]
+
+
+def item(category: str, item_id: str, *, label: str, source: str, aliases: set[str]) -> dict[str, Any]:
+    return {"category": category, "id": item_id, "label": label, "source": source, "aliases": sorted(aliases)}
+
+
+def aliases_for(item_id: str, label: Any = None) -> set[str]:
+    values = {normalize(item_id)}
+    if label:
+        values.add(normalize(str(label)))
+    values.add(normalize(item_id.replace("-", " ")))
+    values.add(normalize(item_id.replace("_", " ")))
+    for token in re.split(r"[-_\s]+", item_id):
+        normalized = normalize(token)
+        if normalized and normalized not in {"cli", "mcp", "api", "tool", "skill", "plugin"}:
+            values.add(normalized)
+    if item_id.endswith("-cli"):
+        values.add(normalize(item_id.removesuffix("-cli")))
+    if item_id.endswith("-mcp"):
+        values.add(normalize(item_id.removesuffix("-mcp")))
+    return {value for value in values if value}
+
+
+def detect_action(prompt: str) -> str | None:
+    if contains_any(prompt, LIST_MARKERS):
+        return "list"
+    if contains_any(prompt, FORGET_MARKERS) and contains_any(prompt, DECISION_MARKERS) and detect_category(prompt):
+        return "reset"
+    if contains_any(prompt, FORGET_MARKERS) and contains_any(prompt, DECISION_MARKERS):
+        return "forget"
+    if contains_any(prompt, FORGET_MARKERS) and detect_category(prompt):
+        return "reset"
+    if contains_any(prompt, DISABLE_MARKERS):
+        return "disable"
+    if contains_any(prompt, ENABLE_MARKERS):
+        return "enable"
+    return None
+
+
+def detect_category(prompt: str) -> str | None:
+    for category, aliases in CATEGORY_ALIASES.items():
+        if contains_any(prompt, aliases):
+            return category
+    return None
+
+
+def list_payload(root: Path, *, category: str | None) -> dict[str, Any]:
+    index = build_control_index(root)
+    if category:
+        result = {
+            "kind": "control-index",
+            "status": "ok",
+            "category": category,
+            "items": public_items(index.get(category, [])),
+            "decisions": list_decisions(category),
+        }
+        return control_payload(status="ok", response=f"Estes sao os itens catalogados para {category}.", result=result)
+    result = {
+        "kind": "control-index",
+        "status": "ok",
+        "categories": {key: public_items(value) for key, value in index.items()},
+        "decisions": list_decisions(),
+    }
+    return control_payload(status="ok", response="Estes sao os recursos controlaveis catalogados.", result=result)
+
+
+def resolve_target(index: dict[str, list[dict[str, Any]]], prompt: str, *, category: str | None) -> list[dict[str, Any]]:
+    candidates = index.get(category, []) if category else [item for items in index.values() for item in items]
+    prompt_tokens = set(TOKEN_PATTERN.findall(prompt))
+    matches = []
+    for candidate in candidates:
+        aliases = set(candidate.get("aliases") or [])
+        if any(alias_matches_prompt(alias, prompt, prompt_tokens) for alias in aliases):
+            matches.append(candidate)
+            continue
+        candidate_tokens = set(TOKEN_PATTERN.findall(normalize(str(candidate.get("id") or ""))))
+        if candidate_tokens and candidate_tokens <= prompt_tokens:
+            matches.append(candidate)
+    return sorted(unique_matches(matches), key=lambda item: (str(item["category"]), str(item["id"])))
+
+
+def unique_matches(matches: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    seen: set[tuple[str, str]] = set()
+    unique = []
+    for match in matches:
+        key = (str(match.get("category")), str(match.get("id")))
+        if key not in seen:
+            seen.add(key)
+            unique.append(match)
+    return unique
+
+
+def alias_matches_prompt(alias: str, prompt: str, prompt_tokens: set[str]) -> bool:
+    if not alias:
+        return False
+    alias_tokens = set(TOKEN_PATTERN.findall(alias))
+    if len(alias_tokens) == 1:
+        return alias in prompt_tokens
+    return alias in prompt
+
+
+def needs_input_unknown(root: Path, prompt: str, *, category: str | None) -> dict[str, Any]:
+    index = build_control_index(root)
+    categories = [category] if category else sorted(index)
+    return {
+        "kind": "agent",
+        "status": "needs-input",
+        "ok": False,
+        "mode": "control-center-route",
+        "requires_llm": False,
+        "unknown_control_target": True,
+        "category": category,
+        "prompt": prompt,
+        "available_categories": categories,
+        "response": "Nao encontrei esse recurso nos catalogos locais controlaveis.",
+        "result": {"categories": {key: public_items(index.get(key, [])) for key in categories}},
+        "exit_code": 2,
+    }
+
+
+def needs_input_ambiguous(matches: list[dict[str, Any]], prompt: str, *, category: str | None) -> dict[str, Any]:
+    return {
+        "kind": "agent",
+        "status": "needs-input",
+        "ok": False,
+        "mode": "control-center-route",
+        "requires_llm": False,
+        "ambiguous_control_target": True,
+        "category": category,
+        "prompt": prompt,
+        "matches": public_items(matches),
+        "response": "Encontrei mais de um recurso compativel. Informe a categoria ou id exato.",
+        "exit_code": 2,
+    }
+
+
+def control_payload(*, status: str, response: str, result: dict[str, Any]) -> dict[str, Any]:
+    return {"kind": "agent", "status": status, "ok": status == "ok", "mode": "control-center-route", "requires_llm": False, "response": response, "result": result}
+
+
+def public_items(items: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    return [{"category": item.get("category"), "id": item.get("id"), "label": item.get("label"), "source": item.get("source")} for item in items]
+
+
+def contains_any(prompt: str, markers: tuple[str, ...]) -> bool:
+    return any(normalize(marker) in prompt for marker in markers)
+
+
+def normalize(value: str) -> str:
+    return " ".join(value.lower().split())

package/runtime/cli/aikit/decision_store.py

@@ -122,6 +122,23 @@ def reset_decisions(category: str | None = None) -> dict[str, Any]:
     return {"kind": "decisions-reset", "status": "reset", "category": category, "path": str(path)}
 
 
+def forget_decision(category: str, item_id: str) -> dict[str, Any]:
+    validate_category(category)
+    validate_item_id(item_id)
+    data = load_decisions()
+    key = decision_key(category, item_id)
+    removed = data.get("items", {}).pop(key, None)
+    path = save_decisions(data)
+    return {
+        "kind": "decision-forget",
+        "status": "forgotten" if isinstance(removed, dict) else "not-found",
+        "path": str(path),
+        "category": category,
+        "id": item_id,
+        "removed": public_decision(removed) if isinstance(removed, dict) else None,
+    }
+
+
 def is_disabled(category: str, item_id: str) -> bool:
     decision = get_decision(category, item_id)
     return bool(decision and decision.get("state") in {"disabled_by_user", "denied_by_user"})

package/runtime/cli/aikit/diagnostics.py

@@ -7,7 +7,7 @@ import os
 from pathlib import Path
 from typing import Any
 
-from cli.aikit.app_home import APP_DIRS, app_home
+from cli.aikit.app_home import APP_DIRS, app_home, app_home_status
 from cli.aikit.llm import config_path as llm_config_path
 from cli.aikit.llm import doctor_backends
 from cli.aikit.lock import lock_path, lock_status, read_lock
@@ -44,6 +44,7 @@ def runtime_diagnostics(
         "status": status,
         "root": str(root),
         "app_home": str(app_home()),
+        "app_home_status": app_home_status(),
         "app_dirs": {
             name: {
                 "path": str(app_home() / name),