agent-devkit 0.1.5 → 0.2.0

package/runtime/cli/aikit/router_explain.py

@@ -0,0 +1,152 @@
+"""Explain Agent DevKit routing decisions without executing capabilities."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from cli.aikit.agent_registry import find_capability, load_agent_registry
+from cli.aikit.memory import redact_secrets
+from cli.aikit.orchestrator import decide_routing
+from cli.aikit.router import route_prompt
+from cli.aikit.runtime_paths import ROOT
+
+
+ROUTE_EXPLAIN_SCHEMA_VERSION = "agent-devkit.route-explain/v1"
+
+
+def explain_route(prompt: str, root: Path | None = None) -> dict[str, Any]:
+    root = root or ROOT
+    prompt = (prompt or "").strip()
+    registry = load_agent_registry(root)
+    deterministic_route = route_prompt(prompt, root=root)
+    decision = decide_routing(registry, prompt, deterministic_route)
+    selected_agent = decision.get("selected_agent_id")
+    selected_capability = decision.get("selected_capability_id")
+    capability = (
+        find_capability(registry, str(selected_agent), str(selected_capability))
+        if selected_agent and selected_capability
+        else None
+    )
+    blockers = blockers_for_capability(capability)
+    route_status = str(decision.get("status") or "")
+    has_executable_selection = bool(selected_agent and selected_capability)
+    explain_decision = "selected" if route_status in {"selected", "deterministic"} and has_executable_selection else "needs-input"
+    return {
+        "kind": "route-explain",
+        "schema_version": ROUTE_EXPLAIN_SCHEMA_VERSION,
+        "status": "ok",
+        "execution": "not-executed",
+        "prompt": redact_secrets(prompt),
+        "normalized_prompt": " ".join(prompt.lower().split()),
+        "intent": intent_for(decision, deterministic_route),
+        "decision": explain_decision,
+        "routing_status": route_status,
+        "selected": {
+            "agent_id": selected_agent,
+            "capability_id": selected_capability,
+        },
+        "score": decision.get("score"),
+        "confidence": decision.get("confidence"),
+        "confidence_label": decision.get("confidence_label"),
+        "method": decision.get("method"),
+        "signals": signal_summary(decision),
+        "candidates": normalize_candidates(decision.get("candidates") or []),
+        "providers_required": providers_for_capability(capability),
+        "source_contract": (capability or {}).get("source_contract"),
+        "write_policy": (capability or {}).get("write_policy"),
+        "write_policy_metadata": (capability or {}).get("write_policy_metadata"),
+        "missing_configuration": blockers,
+        "will_use": {
+            "automation": bool(capability and capability.get("has_runner")),
+            "mini_brain": False,
+            "external_llm": False,
+            "human": explain_decision == "needs-input",
+        },
+        "reason": decision.get("reason"),
+        "question": decision.get("question"),
+        "options": decision.get("options") or [],
+        "next_step": next_step(explain_decision, selected_agent, selected_capability, blockers),
+    }
+
+
+def intent_for(decision: dict[str, Any], deterministic_route: dict[str, Any] | None) -> str | None:
+    if deterministic_route and deterministic_route.get("intent"):
+        return str(deterministic_route["intent"])
+    entities = decision.get("entities") if isinstance(decision.get("entities"), dict) else {}
+    if entities.get("pr_id"):
+        return "pull-request"
+    if entities.get("card_id"):
+        return "card"
+    selected = decision.get("selected_capability_id")
+    return str(selected) if selected else None
+
+
+def normalize_candidates(candidates: list[Any]) -> list[dict[str, Any]]:
+    normalized = []
+    for candidate in candidates:
+        if not isinstance(candidate, dict):
+            continue
+        normalized.append(
+            {
+                "agent_id": candidate.get("agent_id"),
+                "capability_id": candidate.get("selected_capability_id") or candidate.get("capability_id"),
+                "score": candidate.get("score"),
+                "signals": {
+                    key: candidate.get(key)
+                    for key in sorted(candidate)
+                    if key.startswith("matched_") or key.startswith("selected_capability_matched_")
+                },
+                "legacy_fallback": candidate.get("legacy_fallback") is True,
+            }
+        )
+    return normalized
+
+
+def signal_summary(decision: dict[str, Any]) -> list[str]:
+    signals = []
+    for candidate in normalize_candidates(decision.get("candidates") or [])[:1]:
+        for key, values in (candidate.get("signals") or {}).items():
+            if values:
+                signals.append(f"{key}: {', '.join(str(value) for value in values[:3])}")
+    return signals
+
+
+def providers_for_capability(capability: dict[str, Any] | None) -> list[str]:
+    if not capability:
+        return []
+    providers = []
+    provider = capability.get("provider")
+    if provider:
+        providers.append(str(provider))
+    requires = capability.get("requires") if isinstance(capability.get("requires"), dict) else {}
+    for item in requires.get("providers") or []:
+        if isinstance(item, dict) and item.get("id") and str(item["id"]) not in providers:
+            providers.append(str(item["id"]))
+    return providers
+
+
+def blockers_for_capability(capability: dict[str, Any] | None) -> list[dict[str, Any]]:
+    if not capability:
+        return []
+    blockers = []
+    for provider in providers_for_capability(capability):
+        blockers.append({"type": "provider-readiness", "provider": provider, "status": "not-checked"})
+    return blockers
+
+
+def next_step(
+    decision: str,
+    selected_agent: Any,
+    selected_capability: Any,
+    blockers: list[dict[str, Any]],
+) -> str:
+    if decision != "selected":
+        if selected_agent and not selected_capability:
+            return f"Choose a capability for agent `{selected_agent}` before execution."
+        return "Ask the user to choose an agent/capability or provide more context."
+    if blockers:
+        return "Check provider/source readiness before execution."
+    if selected_agent and selected_capability:
+        return f"Run `agent run {selected_agent} {selected_capability}` if execution is desired."
+    return "Review routing decision before execution."

package/runtime/cli/aikit/runtime_paths.py

@@ -0,0 +1,11 @@
+"""Shared runtime paths for the Agent DevKit CLI."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+DEFAULT_ROOT = Path(__file__).resolve().parents[2]
+ROOT = Path(os.environ.get("AI_DEVKIT_ROOT", DEFAULT_ROOT)).resolve()
+AGENTS_DIR = ROOT / "agents"

package/runtime/cli/aikit/secrets.py

@@ -0,0 +1,113 @@
+"""Safe secret reference diagnostics for Agent DevKit."""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import re
+import shutil
+from pathlib import Path
+from typing import Any
+
+from cli.aikit.app_home import ensure_app_home, secrets_home
+from cli.aikit.errors import DevKitError
+
+
+SECRET_REF_SCHEMA_VERSION = "agent-devkit.secrets/v1"
+
+
+def secrets_doctor() -> dict[str, Any]:
+    return {
+        "kind": "secrets-doctor",
+        "schema_version": SECRET_REF_SCHEMA_VERSION,
+        "status": "ok",
+        "stored_values": False,
+        "home": str(secrets_home()),
+        "backends": secret_backends()["backends"],
+        "references": load_secret_references()["references"],
+        "environment": {
+            "secret_like_variables_detected": len(secret_like_env_names()),
+            "names": secret_like_env_names(),
+            "values_redacted": True,
+        },
+    }
+
+
+def secret_backends() -> dict[str, Any]:
+    system = platform.system().lower()
+    backends = [
+        {"id": "env", "status": "available", "stores_values": False},
+        {"id": "local-reference-file", "status": "available", "stores_values": False, "path": str(references_path())},
+        {"id": "macos-keychain", "status": "available" if shutil.which("security") else "unavailable", "platform": "Darwin"},
+        {"id": "windows-credential-manager", "status": "available" if system == "windows" else "unavailable", "platform": "Windows"},
+        {"id": "linux-secret-service", "status": "available" if shutil.which("secret-tool") else "unavailable", "platform": "Linux"},
+    ]
+    return {"kind": "secret-backends", "schema_version": SECRET_REF_SCHEMA_VERSION, "status": "ok", "backends": backends}
+
+
+def add_secret_reference(provider: str, key: str, *, env: str | None) -> dict[str, Any]:
+    provider = require_name(provider, "provider")
+    key = require_name(key, "key")
+    if not env:
+        raise DevKitError("secrets reference add requires --env VAR_NAME")
+    data = load_secret_references()
+    refs = [item for item in data["references"] if not (item["provider"] == provider and item["key"] == key)]
+    refs.append({"provider": provider, "key": key, "backend": "env", "env": env, "value_stored": False})
+    data["references"] = sorted(refs, key=lambda item: (item["provider"], item["key"]))
+    save_secret_references(data)
+    return {"kind": "secret-reference", "status": "saved", "reference": refs[-1], "value_stored": False}
+
+
+def list_secret_references() -> dict[str, Any]:
+    data = load_secret_references()
+    return {"kind": "secret-references", "schema_version": SECRET_REF_SCHEMA_VERSION, "status": "ok", "references": data["references"]}
+
+
+def remove_secret_reference(provider: str, key: str) -> dict[str, Any]:
+    provider = require_name(provider, "provider")
+    key = require_name(key, "key")
+    data = load_secret_references()
+    before = len(data["references"])
+    data["references"] = [item for item in data["references"] if not (item["provider"] == provider and item["key"] == key)]
+    save_secret_references(data)
+    return {"kind": "secret-reference-remove", "status": "removed" if len(data["references"]) < before else "not-found"}
+
+
+def references_path() -> Path:
+    ensure_app_home()
+    return secrets_home() / "references.json"
+
+
+def load_secret_references() -> dict[str, Any]:
+    path = references_path()
+    if not path.exists():
+        return {"version": 1, "references": []}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return {"version": 1, "references": []}
+    if not isinstance(data, dict) or not isinstance(data.get("references"), list):
+        return {"version": 1, "references": []}
+    safe_refs = []
+    for item in data["references"]:
+        if isinstance(item, dict):
+            safe_refs.append({key: value for key, value in item.items() if key != "value"} | {"value_stored": False})
+    return {"version": 1, "references": safe_refs}
+
+
+def save_secret_references(data: dict[str, Any]) -> Path:
+    path = references_path()
+    path.write_text(json.dumps(data, ensure_ascii=False, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return path
+
+
+def secret_like_env_names() -> list[str]:
+    pattern = re.compile(r"(^|[_-])(API[_-]?KEY|KEY|TOKEN|SECRET|PASSWORD|PASS|PAT)([_-]|$)", re.IGNORECASE)
+    return sorted(name for name in os.environ if pattern.search(name))
+
+
+def require_name(value: str | None, label: str) -> str:
+    if not value or not value.strip():
+        raise DevKitError(f"{label} is required")
+    return value.strip()

package/runtime/cli/aikit/sessions.py

@@ -10,7 +10,9 @@ from pathlib import Path
 from typing import Any
 
 from cli.aikit.app_home import app_path, ensure_app_home, sessions_home
+from cli.aikit.autonomy import summarize_autonomy_contract
 from cli.aikit.memory import redact_secrets
+from cli.aikit.mini_brain import summarize_mini_brain
 
 
 SESSION_ID_PATTERN = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9_.-]*$")
@@ -168,6 +170,9 @@ def record_exchange(
         "ok": result.get("ok"),
         "backend": result.get("llm_backend") or backend,
         "requires_llm": result.get("requires_llm"),
+        "autonomy_contract": summarize_autonomy_contract(result.get("autonomy_contract")),
+        "execution_plan": summarize_execution_plan(result.get("execution_plan")),
+        "orchestration_trace": result.get("orchestration_trace") or [],
         "token_estimate": token_delta,
     }
     with (path / "messages.jsonl").open("a", encoding="utf-8") as file:
@@ -189,10 +194,128 @@ def record_exchange(
     return public_session(state, active=True)
 
 
+def summarize_execution_plan(plan: Any) -> dict[str, Any] | None:
+    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": [
+            {
+                "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 plan.get("specialist_tasks") or []
+            if isinstance(task, dict)
+        ],
+        "configuration_tasks": [
+            {
+                "task_id": task.get("task_id") or task.get("id"),
+                "agent_id": task.get("agent_id"),
+                "provider": task.get("provider"),
+                "role": task.get("role"),
+                "depends_on": list(task.get("depends_on") or []),
+                "status": task.get("status"),
+            }
+            for task in plan.get("configuration_tasks") or []
+            if isinstance(task, dict)
+        ],
+        "review_task": {
+            "task_id": (plan.get("review_task") or {}).get("task_id") or (plan.get("review_task") or {}).get("id"),
+            "agent_id": (plan.get("review_task") or {}).get("agent_id"),
+            "role": (plan.get("review_task") or {}).get("role"),
+            "depends_on": list((plan.get("review_task") or {}).get("depends_on") or []),
+            "status": (plan.get("review_task") or {}).get("status"),
+        }
+        if isinstance(plan.get("review_task"), dict)
+        else None,
+        "collaboration_enabled": plan.get("collaboration_enabled") is True,
+        "collaboration_graph": summarize_collaboration_graph(plan.get("collaboration_graph")),
+        "model_plan": summarize_model_plan(plan.get("model_plan")),
+        "execution_model": summarize_execution_model(plan.get("execution_model")),
+        "autonomy_contract": summarize_autonomy_contract(plan.get("autonomy_contract")),
+        "human_escalations": len(plan.get("human_escalations") or []),
+        "shared_context": summarize_shared_context(plan.get("shared_context")),
+    }
+
+
+def summarize_collaboration_graph(value: Any) -> dict[str, Any] | None:
+    if not isinstance(value, dict):
+        return None
+    return {
+        "schema_version": value.get("schema_version"),
+        "nodes": len(value.get("nodes") or []),
+        "edges": len(value.get("edges") or []),
+        "parallel_groups": len(value.get("parallel_groups") or []),
+    }
+
+
+def summarize_shared_context(value: Any) -> dict[str, int] | None:
+    if not isinstance(value, dict):
+        return None
+    return {
+        key: len(value.get(key) or [])
+        for key in (
+            "facts",
+            "inferences",
+            "artifacts",
+            "blockers",
+            "decisions",
+            "risks",
+            "questions",
+            "handoffs",
+            "conflicts",
+            "human_escalations",
+        )
+    }
+
+
+def summarize_execution_model(value: Any) -> dict[str, Any] | None:
+    if not isinstance(value, dict):
+        return None
+    return {
+        "schema_version": value.get("schema_version"),
+        "decision_owner": value.get("decision_owner"),
+        "review_required": value.get("review_required"),
+        "model_strategy": value.get("model_strategy"),
+        "model_risk": value.get("model_risk"),
+        "model_confidence": value.get("model_confidence"),
+        "autonomy_level": value.get("autonomy_level"),
+        "autonomy_level_id": value.get("autonomy_level_id"),
+        "autonomy_status": value.get("autonomy_status"),
+        "execution_allowed": value.get("execution_allowed"),
+        "requires_human": value.get("requires_human"),
+        "limits": value.get("limits") if isinstance(value.get("limits"), dict) else {},
+        "stop_conditions": list(value.get("stop_conditions") or []),
+    }
+
+
+def summarize_model_plan(value: Any) -> dict[str, Any] | None:
+    if not isinstance(value, dict):
+        return None
+    return {
+        "strategy": value.get("strategy"),
+        "risk": value.get("risk"),
+        "confidence": value.get("confidence"),
+        "fallback": value.get("fallback"),
+        "local_llm_selected": value.get("local_llm_selected") is True,
+        "local_llm_recommended": value.get("local_llm_recommended") is True,
+        "mini_brain": summarize_mini_brain(value.get("mini_brain")),
+        "max_llm_calls": value.get("max_llm_calls"),
+    }
+
+
 def build_contextual_prompt(session_id: str, prompt: str) -> str:
     exchanges = recent_exchanges(session_id, limit=RECENT_CONTEXT_EXCHANGES)
+    safe_prompt = redact_secrets(prompt)
     if not exchanges:
-        return prompt
+        return safe_prompt
     lines = [
         "Contexto recente da sessao atual do Agent DevKit:",
     ]
@@ -203,7 +326,7 @@ def build_contextual_prompt(session_id: str, prompt: str) -> str:
             lines.append(f"- Usuario: {previous_prompt}")
         if previous_response:
             lines.append(f"  Assistente: {previous_response}")
-    lines.extend(["", "Pedido atual do usuario:", prompt])
+    lines.extend(["", "Pedido atual do usuario:", safe_prompt])
     return "\n".join(lines)
 
 

package/runtime/cli/aikit/setup_wizard_payload.py

@@ -0,0 +1,32 @@
+"""Shared setup wizard payload helpers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cli.aikit.wizard_state import create_provider_wizard
+
+
+def persist_setup_wizard_payload(
+    payload: dict[str, Any],
+    *,
+    execution_plan: dict[str, Any] | None = None,
+    route: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    wizard = payload.get("setup_wizard")
+    if not isinstance(wizard, dict) or wizard.get("wizard_id"):
+        return payload
+    persisted = create_provider_wizard(
+        wizard,
+        execution_plan=execution_plan or payload.get("execution_plan"),
+        route=route or payload.get("route"),
+    )
+    payload["setup_wizard"] = persisted
+    payload["next_question"] = persisted.get("next_question")
+    if execution_plan and execution_plan.get("configuration_tasks"):
+        for task in execution_plan.get("configuration_tasks") or []:
+            if isinstance(task, dict) and task.get("provider") == persisted.get("provider"):
+                task["setup_wizard"] = persisted
+                break
+    payload.setdefault("wizard_id", persisted.get("wizard_id"))
+    return payload