agent-devkit 0.1.5 → 0.2.0

package/runtime/cli/aikit/impact_map.py

@@ -0,0 +1,294 @@
+"""Technical ownership and impact map for Agent DevKit changes."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any
+
+
+OWNERSHIP_AREAS: list[dict[str, Any]] = [
+    {
+        "id": "cli",
+        "name": "CLI",
+        "paths": [
+            "cli/aikit/main.py",
+            "cli/aikit/cli_parser.py",
+            "cli/aikit/cli_dispatch.py",
+            "cli/aikit/human_output.py",
+            "agent",
+            "aikit",
+            "ai-devkit",
+        ],
+        "responsibilities": [
+            "argument parsing",
+            "public commands",
+            "human and JSON output",
+            "exit codes",
+            "TTY-facing behavior",
+        ],
+        "should_not_contain": [
+            "agent domain rules",
+            "provider-specific knowledge",
+            "capability-only contracts",
+        ],
+    },
+    {
+        "id": "core_execution",
+        "name": "Core De Planejamento E Execucao",
+        "paths": [
+            "cli/aikit/orchestrator.py",
+            "cli/aikit/agent_executor.py",
+            "cli/aikit/capability_runtime.py",
+            "cli/aikit/core/*",
+        ],
+        "responsibilities": [
+            "execution planning",
+            "task selection",
+            "capability execution",
+            "guardrail entry points",
+            "review gate integration",
+        ],
+        "should_not_contain": [
+            "host-specific adapters",
+            "provider credentials",
+            "large prompt knowledge",
+        ],
+    },
+    {
+        "id": "registry",
+        "name": "Registry",
+        "paths": [
+            "cli/aikit/agent_registry.py",
+            "agents/*/agent.yaml",
+            "agents/*/capabilities/*/capability.yaml",
+        ],
+        "responsibilities": [
+            "agent loading",
+            "capability loading",
+            "declarative metadata normalization",
+            "manifest contract exposure",
+        ],
+        "should_not_contain": [
+            "runner execution logic",
+            "duplicated YAML readers",
+            "provider transport code",
+        ],
+    },
+    {
+        "id": "policies_guardrails",
+        "name": "Policies E Guardrails",
+        "paths": [
+            "cli/aikit/write_policy.py",
+            "cli/aikit/guardrails.py",
+            "cli/aikit/permissions.py",
+            "cli/aikit/review_gate.py",
+        ],
+        "responsibilities": [
+            "canonical write policy",
+            "confirmation requirements",
+            "permission checks",
+            "blocked-by-default behavior",
+        ],
+        "should_not_contain": [
+            "provider implementation details",
+            "capability-specific business rules",
+            "host login flow",
+        ],
+    },
+    {
+        "id": "providers_sources",
+        "name": "Providers, Credentials E Sources",
+        "paths": [
+            "cli/aikit/providers.py",
+            "cli/aikit/credentials.py",
+            "cli/aikit/sources.py",
+            "cli/aikit/fallback.py",
+            "providers/*.yaml",
+            "agents/*/infra/integrations/*",
+        ],
+        "responsibilities": [
+            "provider registry",
+            "credential references",
+            "provider readiness",
+            "fallback behavior",
+            "source configuration",
+        ],
+        "should_not_contain": [
+            "hardcoded secrets",
+            "mandatory host coupling",
+            "agent prompt policy",
+        ],
+    },
+    {
+        "id": "llm_mini_brain",
+        "name": "LLMs E Mini Cerebro",
+        "paths": [
+            "cli/aikit/llm.py",
+            "cli/aikit/model_router.py",
+            "cli/aikit/local_llm_operator.py",
+            "cli/aikit/ollama.py",
+        ],
+        "responsibilities": [
+            "LLM backend registry",
+            "backend preference and fallback",
+            "local model operation",
+            "decision limits for simple conversation",
+        ],
+        "should_not_contain": [
+            "provider-specific domain repositories",
+            "scheduler persistence",
+            "host-specific tool schemas",
+        ],
+    },
+    {
+        "id": "sessions_memory_tasks_scheduler",
+        "name": "Sessions, Memory, Tasks E Scheduler",
+        "paths": [
+            "cli/aikit/sessions.py",
+            "cli/aikit/memory.py",
+            "cli/aikit/tasks.py",
+            "cli/aikit/scheduler.py",
+            "cli/aikit/calendar.py",
+            "cli/aikit/notifications.py",
+        ],
+        "responsibilities": [
+            "conversation continuity",
+            "local state",
+            "scheduled tasks",
+            "calendar integration",
+            "notifications",
+        ],
+        "should_not_contain": [
+            "core routing policy",
+            "provider transport internals",
+            "manifest validation rules",
+        ],
+    },
+    {
+        "id": "audit",
+        "name": "Auditoria",
+        "paths": [
+            "cli/aikit/audit.py",
+            "cli/aikit/cli_dispatch.py",
+            "cli/aikit/main.py",
+        ],
+        "responsibilities": [
+            "operational trail",
+            "redaction",
+            "export",
+            "execution origin",
+            "audit warnings",
+        ],
+        "should_not_contain": [
+            "business-domain analysis",
+            "provider credentials",
+            "large artifacts",
+        ],
+    },
+    {
+        "id": "mcp",
+        "name": "MCP",
+        "paths": [
+            "cli/aikit/mcp_server.py",
+            "cli/aikit/mcp_tools.py",
+            "cli/aikit/mcp_manifest.py",
+        ],
+        "responsibilities": [
+            "stdio server",
+            "tool schemas",
+            "calls into Agent DevKit core",
+            "host-agnostic MCP surface",
+        ],
+        "should_not_contain": [
+            "Hermes-only behavior",
+            "OpenClaw-only behavior",
+            "OpenCode-only behavior",
+        ],
+    },
+    {
+        "id": "validation_gates",
+        "name": "Validacao E Gates",
+        "paths": [
+            "scripts/validate-repo.py",
+            "scripts/release-gate.py",
+            "tests/*",
+            ".github/workflows/*",
+        ],
+        "responsibilities": [
+            "repository structure validation",
+            "manifest contracts",
+            "release gates",
+            "regression tests",
+        ],
+        "should_not_contain": [
+            "runtime-only side effects",
+            "provider credentials",
+            "generated local docs",
+        ],
+    },
+    {
+        "id": "agents_capabilities",
+        "name": "Agentes E Capabilities",
+        "paths": [
+            "agents/<agent-id>/agent.yaml",
+            "agents/<agent-id>/AGENTS.md",
+            "agents/<agent-id>/README.md",
+            "agents/<agent-id>/capabilities/*",
+            "agents/<agent-id>/knowledge/*",
+            "agents/<agent-id>/templates/*",
+            "agents/<agent-id>/infra/*",
+        ],
+        "responsibilities": [
+            "domain ownership",
+            "capability workflows",
+            "runner behavior",
+            "repositories",
+            "templates",
+            "on-demand knowledge",
+        ],
+        "should_not_contain": [
+            "global runtime policy unless delegated",
+            "unrelated agent changes",
+            "host-specific core coupling",
+        ],
+    },
+]
+
+
+SPEC_IMPACT_TEMPLATE: dict[str, str] = {
+    "likely_files": "Arquivos, modulos, manifests ou contratos provavelmente impactados.",
+    "files_not_to_touch": "Arquivos e dominios que devem permanecer fora do patch.",
+    "affected_contracts": "Contratos publicos, manifests, schemas, comandos ou payloads afetados.",
+    "related_gates": "Testes, validators, release gates ou smoke tests relacionados.",
+    "compatibility_risks": "Riscos de compatibilidade com CLI, hosts, agentes, providers ou usuarios existentes.",
+    "boundary_crossing_justification": "Justificativa quando a mudanca cruza ownership de core, agente, provider, host ou gate.",
+}
+
+
+OWNERSHIP_RULES: list[str] = [
+    "Identificar se a mudanca pertence a core, agente, provider, host, docs ou gate antes de implementar.",
+    "Tocar apenas arquivos do ownership correto sempre que possivel.",
+    "Justificar qualquer cruzamento de boundary no plano, PR ou resposta de entrega.",
+    "Evitar alteracoes em massa de manifests sem spec explicita.",
+    "Evitar alterar runtime central para resolver caso especifico de um agente.",
+]
+
+
+def ownership_area_ids() -> list[str]:
+    """Return canonical technical ownership area identifiers."""
+    return [area["id"] for area in OWNERSHIP_AREAS]
+
+
+def spec_impact_template() -> dict[str, str]:
+    """Return the canonical impact template for specs and PRs."""
+    return dict(SPEC_IMPACT_TEMPLATE)
+
+
+def ownership_model() -> dict[str, Any]:
+    """Return the canonical technical ownership and impact model."""
+    return {
+        "schema_version": "ai-devkit.impact/v1",
+        "areas": deepcopy(OWNERSHIP_AREAS),
+        "spec_template": spec_impact_template(),
+        "rules": list(OWNERSHIP_RULES),
+    }

package/runtime/cli/aikit/install.py

@@ -9,7 +9,7 @@ from pathlib import Path
 from typing import Any
 
 from cli.aikit import __version__
-from cli.aikit.lock import lock_path, write_lock
+from cli.aikit.lock import GLOBAL_RUNTIME_DIR, PROJECT_RUNTIME_DIR, lock_path, write_lock
 
 
 HOST_ALIASES = {
@@ -46,7 +46,7 @@ def install_runtime(
     hosts = resolve_hosts(host)
     root = root.resolve()
     base = resolve_base(scope, target=target, home=home)
-    runtime_dir = base / ".ai-devkit"
+    runtime_dir = base / (GLOBAL_RUNTIME_DIR if scope == "global" else PROJECT_RUNTIME_DIR)
     bin_dir = runtime_dir / "bin"
     config_path = runtime_dir / "config.yaml"
     runtime_lock_path = lock_path(base, scope)
@@ -256,7 +256,8 @@ def write_runtime_config(path: Path, root: Path, scope: str, hosts: tuple[str, .
 
 
 def next_steps(scope: str, hosts: tuple[str, ...]) -> list[str]:
-    steps = ["Add `.ai-devkit/bin` to PATH when you want to call the installed `agent` directly."]
+    runtime_dir_name = GLOBAL_RUNTIME_DIR if scope == "global" else PROJECT_RUNTIME_DIR
+    steps = [f"Add `{runtime_dir_name}/bin` to PATH when you want to call the installed `agent` directly."]
     steps.append("Run `agent doctor --json` to validate the local runtime.")
     if "codex" in hosts:
         steps.append("Restart or reload Codex so it can discover the AI DevKit plugin/skill.")

package/runtime/cli/aikit/interactive_wizard.py

@@ -0,0 +1,79 @@
+"""Interactive setup wizard flow for CLI TTY sessions."""
+
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+from cli.aikit.core.requests import AgentPromptRequest
+from cli.aikit.core.runtime import run_agent_prompt
+from cli.aikit.wizard_state import WizardStateError, answer_wizard, cancel_wizard, show_wizard
+
+
+def maybe_run_interactive_wizard(result: dict[str, Any]) -> dict[str, Any]:
+    if not sys.stdin.isatty() or not sys.stdout.isatty():
+        return result
+    wizard = result.get("setup_wizard") if isinstance(result.get("setup_wizard"), dict) else None
+    if not wizard or not wizard.get("wizard_id") or result.get("status") != "needs-input":
+        return result
+    print(result.get("message") or "O agente precisa de configuracao antes de continuar.")
+    return run_interactive_wizard(str(wizard["wizard_id"]))
+
+
+def run_interactive_wizard(wizard_id: str) -> dict[str, Any]:
+    payload = show_wizard(wizard_id)
+    while True:
+        wizard = payload.get("wizard") if isinstance(payload.get("wizard"), dict) else {}
+        question = payload.get("next_question") or wizard.get("next_question")
+        if not isinstance(question, dict):
+            return payload
+        print_interactive_question(question)
+        try:
+            answer = input("> ")
+        except (EOFError, KeyboardInterrupt):
+            print()
+            return cancel_wizard(wizard_id, reason="interactive wizard interrupted")
+        if answer.strip().lower() in {"cancelar", "cancel", "sair", "exit"}:
+            return cancel_wizard(wizard_id, reason="interactive wizard cancelled by user")
+        try:
+            payload = answer_wizard(wizard_id, answer)
+        except WizardStateError as exc:
+            print(f"Erro: {exc}")
+            continue
+        if payload.get("status") == "completed":
+            resume_prompt = payload.get("resume_prompt") or (payload.get("wizard") or {}).get("resume_prompt")
+            if resume_prompt:
+                payload["resumed_prompt"] = True
+                payload["resume_result"] = resume_agent_prompt(str(resume_prompt))
+            else:
+                payload["resumed_prompt"] = False
+            return payload
+        if payload.get("status") in {"cancelled", "denied-by-user", "failed"}:
+            payload.setdefault("resumed_prompt", False)
+            return payload
+
+
+def print_interactive_question(question: dict[str, Any]) -> None:
+    text = question.get("text") or "Informe a resposta."
+    print(f"\nPergunta: {text}")
+    if question.get("type") == "confirm":
+        print("[s/N]")
+    options = question.get("options")
+    if isinstance(options, list) and options:
+        print("Opcoes: " + ", ".join(str(item) for item in options))
+    if question.get("suggested_value"):
+        print(f"Sugestao: {question['suggested_value']}")
+    if question.get("env_ref_key"):
+        print("Informe o nome da variavel de ambiente, nao o valor da credencial.")
+    print("Digite 'cancelar' para interromper.")
+
+
+def resume_agent_prompt(prompt: str) -> dict[str, Any]:
+    result = run_agent_prompt(
+        AgentPromptRequest(
+            prompt=prompt,
+            prog_name="agent",
+        )
+    )
+    result.pop("audit", None)
+    return result

package/runtime/cli/aikit/local_llm_operator.py

@@ -0,0 +1,146 @@
+"""Runtime execution for the local-llm-operator agent."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cli.aikit.llm import invoke_agent_prompt
+from cli.aikit.memory import redact_secrets
+from cli.aikit.mini_brain import summarize_mini_brain
+
+
+FORBIDDEN_DELEGATION_MARKERS = (
+    "aprove",
+    "aprovar",
+    "reprove",
+    "reprovar",
+    "deploy",
+    "delete",
+    "excluir",
+    "execute escrita",
+    "permissao",
+    "permissão",
+)
+
+
+def maybe_delegate_local_llm(prompt: str, model_plan: dict[str, Any]) -> dict[str, Any]:
+    """Execute a bounded operational task with Ollama when the model plan selected it."""
+    delegation = model_plan.get("delegation") if isinstance(model_plan.get("delegation"), dict) else {}
+    if model_plan.get("strategy") != "mini-brain":
+        return skipped(
+            "strategy-not-mini-brain",
+            "Local LLM delegation was not selected by the model strategy.",
+            model_plan=model_plan,
+        )
+    if model_plan.get("risk") == "high":
+        return skipped(
+            "high-risk",
+            "High-risk tasks cannot be delegated to local LLM workers.",
+            model_plan=model_plan,
+        )
+    if int(model_plan.get("max_llm_calls") or 0) <= 0:
+        return skipped(
+            "llm-budget-not-available",
+            "Model plan does not allow local LLM calls.",
+            model_plan=model_plan,
+        )
+    if not model_plan.get("local_llm_selected") or not delegation.get("selected"):
+        return skipped("not-selected", "Local LLM delegation was not selected for this prompt.", model_plan=model_plan)
+    lowered = prompt.lower()
+    if any(marker in lowered for marker in FORBIDDEN_DELEGATION_MARKERS):
+        return skipped("forbidden", "Prompt contains an action that local LLM workers cannot execute.", model_plan=model_plan)
+    delegated_prompt = build_delegated_prompt(prompt, model_plan)
+    result = invoke_agent_prompt(
+        delegated_prompt,
+        "ollama",
+        public_name="Local LLM Operator",
+        allow_fallback=False,
+    )
+    payload = {
+        "kind": "local-llm-execution",
+        "agent_id": "local-llm-operator",
+        "capability_id": "delegate-operational-task",
+        "capability": "local-llm-operator.delegate-operational-task",
+        "status": "ok" if result.get("ok") else result.get("status", "failed"),
+        "ok": bool(result.get("ok")),
+        "llm_backend": result.get("llm_backend"),
+        "model_provider": "ollama",
+        "mini_brain": summarize_mini_brain(model_plan.get("mini_brain")),
+        "strategy": model_plan.get("strategy"),
+        "risk": model_plan.get("risk"),
+        "confidence": model_plan.get("confidence"),
+        "delegated_prompt": redact_secrets(delegated_prompt),
+        "response": result.get("response"),
+        "result": sanitize_llm_result(result),
+        "requires_review": True,
+    }
+    if not result.get("ok"):
+        payload["message"] = result.get("message") or "Local LLM delegation failed."
+    return payload
+
+
+def build_delegated_prompt(prompt: str, model_plan: dict[str, Any]) -> str:
+    forbidden = ", ".join((model_plan.get("delegation") or {}).get("forbidden_actions") or [])
+    mini_brain = model_plan.get("mini_brain") if isinstance(model_plan.get("mini_brain"), dict) else {}
+    allowed_tasks = ", ".join(mini_brain.get("allowed_tasks") or [])
+    forbidden_tasks = ", ".join(mini_brain.get("forbidden_tasks") or [])
+    limits = mini_brain.get("limits") if isinstance(mini_brain.get("limits"), dict) else {}
+    response_limit = limits.get("max_response_chars") or 2000
+    return "\n".join(
+        [
+            "Execute apenas a parte operacional da tarefa abaixo.",
+            "Nao tome decisao final, nao aprove, nao escreva externamente e nao revise a entrega final.",
+            f"Escopo permitido do mini-brain: {allowed_tasks}.",
+            f"Tarefas proibidas do mini-brain: {forbidden_tasks}.",
+            f"Acoes proibidas: {forbidden}.",
+            f"Retorne no maximo {response_limit} caracteres com resumo estruturado, evidencias extraidas, lacunas e confianca.",
+            "",
+            "Tarefa original:",
+            redact_secrets(prompt),
+        ]
+    )
+
+
+def enrich_prompt_with_local_result(prompt: str, local_execution: dict[str, Any]) -> str:
+    if not local_execution.get("ok") or not local_execution.get("response"):
+        return prompt
+    return "\n".join(
+        [
+            prompt,
+            "",
+            "Contexto operacional produzido pelo local-llm-operator/Ollama:",
+            str(local_execution["response"]),
+            "",
+            "Use esse contexto apenas como apoio. A decisao, resposta final e revisao continuam sob responsabilidade do coordenador.",
+        ]
+    )
+
+
+def skipped(reason: str, message: str, *, model_plan: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "kind": "local-llm-execution",
+        "agent_id": "local-llm-operator",
+        "capability_id": "delegate-operational-task",
+        "capability": "local-llm-operator.delegate-operational-task",
+        "status": "skipped",
+        "ok": False,
+        "reason": reason,
+        "message": message,
+        "model_provider": model_plan.get("local_llm_provider") or "ollama",
+        "mini_brain": summarize_mini_brain(model_plan.get("mini_brain")),
+        "strategy": model_plan.get("strategy"),
+        "risk": model_plan.get("risk"),
+        "confidence": model_plan.get("confidence"),
+        "requires_review": bool(model_plan.get("local_llm_recommended") or model_plan.get("local_llm_selected")),
+    }
+
+
+def sanitize_llm_result(result: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "status": result.get("status"),
+        "ok": result.get("ok"),
+        "llm_backend": result.get("llm_backend"),
+        "llm_backend_attempts": result.get("llm_backend_attempts"),
+        "message": result.get("message"),
+        "exit_code": result.get("exit_code"),
+    }

package/runtime/cli/aikit/lock.py

@@ -14,11 +14,14 @@ from cli.aikit import __version__
 
 PROJECT_LOCK_NAME = "ai-devkit.lock"
 GLOBAL_LOCK_NAME = "runtime.lock"
+PROJECT_RUNTIME_DIR = ".ai-devkit"
+GLOBAL_RUNTIME_DIR = ".agent-devkit"
 
 
 def lock_path(base: Path, scope: str) -> Path:
     name = GLOBAL_LOCK_NAME if scope == "global" else PROJECT_LOCK_NAME
-    return base / ".ai-devkit" / name
+    runtime_dir = GLOBAL_RUNTIME_DIR if scope == "global" else PROJECT_RUNTIME_DIR
+    return base / runtime_dir / name
 
 
 def write_lock(