agent-devkit 0.1.0 → 0.1.6

package/runtime/cli/aikit/main.py

@@ -14,9 +14,16 @@ from typing import Any
 
 from cli.aikit.aliases import add_alias, list_aliases, remove_alias, sync_aliases
 from cli.aikit import __version__
+from cli.aikit.agent_executor import execute_plan_tasks
+from cli.aikit.app_home import app_home_status, migrate_default_home
 from cli.aikit.audit import export_audit, list_audits, record_audit, show_audit
 from cli.aikit.calendar import calendar_list, calendar_summary, calendar_today, calendar_tomorrow, configure_calendar
+from cli.aikit.configuration_orchestrator import provider_wizard_from_requirement
+from cli.aikit.control_router import dispatch_natural_control_prompt as route_natural_control_prompt
+from cli.aikit.control_router import plan_natural_control_prompt
+from cli.aikit.decision_store import forget_decision, list_decisions, reset_decisions, set_decision
 from cli.aikit.diagnostics import build_diagnostics
+from cli.aikit.execution_reviewer import enforce_execution_review
 from cli.aikit.fallback import evaluate_provider_requirements
 from cli.aikit.github_pr import pr_create_automation, pr_inspect, pr_list_review_requests, pr_review
 from cli.aikit.guardrails import evaluate_execution_guardrails
@@ -31,8 +38,19 @@ from cli.aikit.llm import (
     set_llm_preference,
 )
 from cli.aikit.memory import memory_path_payload, napkin_context, record_usage, reset_memory, show_memory
+from cli.aikit.model_router import build_model_plan
+from cli.aikit.ollama import ollama_models, ollama_pull, ollama_status, ollama_update
+from cli.aikit.local_llm_operator import enrich_prompt_with_local_result, maybe_delegate_local_llm
+from cli.aikit.orchestrator import (
+    attach_source_to_primary_task,
+    build_execution_plan,
+    mark_plan_after_execution,
+    mark_review_task,
+)
 from cli.aikit.personality import load_personality, reset_personality, setup_personality, update_personality
 from cli.aikit.permissions import grant_permission, revoke_permission, show_permissions
+from cli.aikit.provider_wizard import missing_source_wizard
+from cli.aikit.review_gate import build_review_gate
 from cli.aikit.sessions import (
     build_contextual_prompt,
     get_or_create_session,
@@ -79,6 +97,14 @@ from cli.aikit.sources import (
     source_env,
     source_status,
 )
+from cli.aikit.wizard_state import (
+    WizardStateError,
+    answer_wizard,
+    cancel_wizard,
+    create_provider_wizard,
+    list_wizards,
+    show_wizard,
+)
 
 
 DEFAULT_ROOT = Path(__file__).resolve().parents[2]
@@ -109,7 +135,14 @@ DETERMINISTIC_COMMANDS = (
     "pr",
     "permissions",
     "audit",
+    "config",
+    "tools",
+    "integrations",
+    "skills",
+    "decisions",
+    "ollama",
     "install",
+    "wizard",
 )
 LLM_COMMANDS = ("agent",)
 
@@ -132,6 +165,8 @@ def main(argv: list[str] | None = None, *, prog: str | None = None) -> int:
 
     if result is None:
         return 0
+    if not getattr(args, "json", False):
+        result = maybe_run_interactive_wizard(result)
     maybe_record_cli_audit(args, result=result, error=None)
 
     if getattr(args, "json", False):
@@ -211,6 +246,14 @@ def build_parser(prog: str | None = None) -> argparse.ArgumentParser:
     source_parser.add_argument("--default-for-agent", action="append", default=[], help="agent id that should use this source by default")
     source_parser.add_argument("--set-default", action="store_true", help="set as default source for its provider")
 
+    wizard_parser = subparsers.add_parser("wizard", help="continue agentic setup wizards")
+    wizard_parser.add_argument("--json", action="store_true", default=argparse.SUPPRESS, help=argparse.SUPPRESS)
+    wizard_parser.add_argument("action", nargs="?", default="list", choices=["list", "show", "answer", "cancel"])
+    wizard_parser.add_argument("wizard_id", nargs="?")
+    wizard_parser.add_argument("answer", nargs="*")
+    wizard_parser.add_argument("--status", help="filter wizard list by status")
+    wizard_parser.add_argument("--no-run", action="store_true", help="do not resume the original prompt after completing a wizard")
+
     memory_parser = subparsers.add_parser("memory", help="inspect or reset local AI DevKit memory")
     memory_parser.add_argument("--json", action="store_true", default=argparse.SUPPRESS, help=argparse.SUPPRESS)
     memory_parser.add_argument("action", nargs="?", default="show", choices=["show", "path", "reset"])
@@ -306,13 +349,41 @@ def build_parser(prog: str | None = None) -> argparse.ArgumentParser:
     audit_parser.add_argument("--limit", type=int, default=20)
     audit_parser.add_argument("--format", default="md", choices=["md", "json"])
 
+    config_parser = subparsers.add_parser("config", help="inspect local Agent DevKit configuration")
+    config_parser.add_argument("--json", action="store_true", default=argparse.SUPPRESS, help=argparse.SUPPRESS)
+    config_parser.add_argument("action", nargs="?", default="show", choices=["show", "path", "migrate-home"])
+    config_parser.add_argument("--dry-run", action="store_true", help="plan home migration without moving files")
+
+    for command_name, help_text in (
+        ("tools", "manage enabled local tools"),
+        ("integrations", "manage provider integration decisions"),
+        ("skills", "manage local skill decisions"),
+    ):
+        control_parser = subparsers.add_parser(command_name, help=help_text)
+        control_parser.add_argument("--json", action="store_true", default=argparse.SUPPRESS, help=argparse.SUPPRESS)
+        control_parser.add_argument("action", nargs="?", default="list", choices=["list", "enable", "disable"])
+        control_parser.add_argument("item_id", nargs="?")
+
+    decisions_parser = subparsers.add_parser("decisions", help="inspect or reset local opt-in and opt-out decisions")
+    decisions_parser.add_argument("--json", action="store_true", default=argparse.SUPPRESS, help=argparse.SUPPRESS)
+    decisions_parser.add_argument("action", nargs="?", default="list", choices=["list", "forget", "reset"])
+    decisions_parser.add_argument("item_id", nargs="?")
+    decisions_parser.add_argument("--category", choices=["tools", "integrations", "skills", "llms"])
+
+    ollama_parser = subparsers.add_parser("ollama", help="inspect and manage local Ollama models")
+    ollama_parser.add_argument("--json", action="store_true", default=argparse.SUPPRESS, help=argparse.SUPPRESS)
+    ollama_parser.add_argument("action", nargs="?", default="status", choices=["status", "models", "pull", "update"])
+    ollama_parser.add_argument("model", nargs="?")
+    ollama_parser.add_argument("--yes", action="store_true", help="confirm Ollama model or update operation")
+    ollama_parser.add_argument("--dry-run", action="store_true", help="show Ollama operation without executing it")
+
     llm_parser = subparsers.add_parser("llm", help="manage LLM backends")
     llm_parser.add_argument("--json", action="store_true", default=argparse.SUPPRESS, help=argparse.SUPPRESS)
     llm_parser.add_argument(
         "action",
         nargs="?",
         default="list",
-        choices=["list", "doctor", "configure", "set-default", "preference"],
+        choices=["list", "doctor", "configure", "set-default", "default", "enable", "disable", "preference"],
     )
     llm_parser.add_argument("backend", nargs="?")
     llm_parser.add_argument("preference_value", nargs="?")
@@ -401,6 +472,8 @@ def dispatch(args: argparse.Namespace) -> dict[str, Any] | None:
         return dispatch_credential(args)
     if command == "source":
         return dispatch_source(args)
+    if command == "wizard":
+        return dispatch_wizard(args)
     if command == "memory":
         return dispatch_memory(args)
     if command == "personality":
@@ -425,6 +498,14 @@ def dispatch(args: argparse.Namespace) -> dict[str, Any] | None:
         return dispatch_permissions(args)
     if command == "audit":
         return dispatch_audit(args)
+    if command == "config":
+        return dispatch_config(args)
+    if command in {"tools", "integrations", "skills"}:
+        return dispatch_control_category(command, args)
+    if command == "decisions":
+        return dispatch_decisions(args)
+    if command == "ollama":
+        return dispatch_ollama(args)
     if command == "llm":
         return dispatch_llm(args)
     if command == "install":
@@ -529,10 +610,15 @@ def dispatch_llm(args: argparse.Namespace) -> dict[str, Any]:
                 command=args.host_command,
                 set_default=args.set_default,
             )
-        if args.action == "set-default":
+        if args.action in {"set-default", "default"}:
             if not args.backend:
-                raise DevKitError("llm set-default requires a backend")
+                raise DevKitError(f"llm {args.action} requires a backend")
             return set_default_backend(args.backend)
+        if args.action in {"enable", "disable"}:
+            if not args.backend:
+                raise DevKitError(f"llm {args.action} requires a backend")
+            state = "enabled" if args.action == "enable" else "disabled_by_user"
+            return set_decision("llms", args.backend, state, reason=f"llm {args.action} command")
         if args.action == "preference":
             if args.backend in {None, "show"}:
                 return llm_preference()
@@ -551,6 +637,88 @@ def dispatch_llm(args: argparse.Namespace) -> dict[str, Any]:
     raise DevKitError(f"unsupported llm action: {args.action}")
 
 
+def dispatch_config(args: argparse.Namespace) -> dict[str, Any]:
+    from cli.aikit.llm import config_path
+
+    if args.action == "path":
+        return {"kind": "config", "status": "ok", "path": str(config_path()), "home": app_home_status()}
+    if args.action == "migrate-home":
+        return migrate_default_home(dry_run=effective_dry_run(args))
+    if args.action == "show":
+        return {
+            "kind": "config",
+            "status": "ok",
+            "path": str(config_path()),
+            "home": app_home_status(),
+            "decisions": list_decisions(),
+            "llm": llm_preference(),
+            "ollama": ollama_status(),
+        }
+    raise DevKitError(f"unsupported config action: {args.action}")
+
+
+def dispatch_control_category(command: str, args: argparse.Namespace) -> dict[str, Any]:
+    try:
+        category = command
+        if args.action == "list":
+            if args.item_id:
+                raise DevKitError(f"{command} list does not accept an item id")
+            payload = list_decisions(category)
+            payload["kind"] = command
+            return payload
+        if args.action in {"enable", "disable"}:
+            if not args.item_id:
+                raise DevKitError(f"{command} {args.action} requires an item id")
+            state = "enabled" if args.action == "enable" else "disabled_by_user"
+            payload = set_decision(category, args.item_id, state, reason=f"{command} {args.action} command")
+            payload["kind"] = command[:-1] if command.endswith("s") else command
+            return payload
+    except ValueError as exc:
+        raise DevKitError(str(exc)) from exc
+    raise DevKitError(f"unsupported {command} action: {args.action}")
+
+
+def dispatch_decisions(args: argparse.Namespace) -> dict[str, Any]:
+    try:
+        if args.action == "list":
+            if args.item_id:
+                raise DevKitError("decisions list does not accept an item id")
+            return list_decisions(args.category)
+        if args.action == "reset":
+            if args.item_id:
+                raise DevKitError("decisions reset does not accept an item id")
+            return reset_decisions(args.category)
+        if args.action == "forget":
+            if not args.item_id:
+                raise DevKitError("decisions forget requires an item id")
+            category = args.category or "tools"
+            return forget_decision(category, args.item_id)
+    except ValueError as exc:
+        raise DevKitError(str(exc)) from exc
+    raise DevKitError(f"unsupported decisions action: {args.action}")
+
+
+def dispatch_ollama(args: argparse.Namespace) -> dict[str, Any]:
+    try:
+        if args.action == "status":
+            if args.model:
+                raise DevKitError("ollama status does not accept a model")
+            return ollama_status()
+        if args.action == "models":
+            if args.model:
+                raise DevKitError("ollama models does not accept a model")
+            return ollama_models()
+        if args.action == "pull":
+            return ollama_pull(args.model, yes=args.yes, dry_run=effective_dry_run(args))
+        if args.action == "update":
+            if args.model:
+                raise DevKitError("ollama update does not accept a model")
+            return ollama_update(yes=args.yes, dry_run=effective_dry_run(args))
+    except ValueError as exc:
+        raise DevKitError(str(exc)) from exc
+    raise DevKitError(f"unsupported ollama action: {args.action}")
+
+
 def dispatch_install(args: argparse.Namespace) -> dict[str, Any]:
     try:
         return install_runtime(
@@ -645,6 +813,117 @@ def dispatch_source(args: argparse.Namespace) -> dict[str, Any]:
     raise DevKitError(f"unsupported source action: {args.action}")
 
 
+def dispatch_wizard(args: argparse.Namespace) -> dict[str, Any]:
+    try:
+        if args.action == "list":
+            return list_wizards(status=args.status)
+        if args.action == "show":
+            require_id(args.wizard_id, "wizard show")
+            return show_wizard(args.wizard_id)
+        if args.action == "cancel":
+            require_id(args.wizard_id, "wizard cancel")
+            return cancel_wizard(args.wizard_id)
+        if args.action == "answer":
+            require_id(args.wizard_id, "wizard answer")
+            answer = " ".join(args.answer or []).strip()
+            if not answer:
+                raise DevKitError("wizard answer requires an answer")
+            payload = answer_wizard(args.wizard_id, answer)
+            if payload.get("status") == "completed" and not args.no_run:
+                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
+            else:
+                payload.setdefault("resumed_prompt", False)
+            return payload
+    except WizardStateError as exc:
+        raise DevKitError(str(exc)) from exc
+    except SourceRegistryError as exc:
+        raise DevKitError(str(exc)) from exc
+    raise DevKitError(f"unsupported wizard action: {args.action}")
+
+
+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]:
+    args = argparse.Namespace(
+        command="agent",
+        prompt=prompt.split(),
+        session_id=None,
+        new_session=False,
+        llm=None,
+        no_llm_fallback=False,
+        dry_run=False,
+        global_dry_run=False,
+        prog_name="agent",
+        json=True,
+        version=False,
+        sessions_shortcut=False,
+    )
+    result = agent_requires_llm(args)
+    result.pop("audit", None)
+    return result
+
+
 def dispatch_memory(args: argparse.Namespace) -> dict[str, Any]:
     if args.action == "show":
         return show_memory(ROOT, agent_id=args.agent_id, source_id=args.source_id)
@@ -962,25 +1241,131 @@ def agent_requires_llm(args: argparse.Namespace) -> dict[str, Any]:
         return finalize_agent_session(natural_result, session, prompt, backend=args.llm)
     route = route_prompt(prompt)
     if route:
-        result = invoke_deterministic_route(prompt, route)
+        result = invoke_agentic_route(prompt, route)
         return finalize_agent_session(result, session, prompt, backend=args.llm)
     contextual_prompt = build_contextual_prompt(str(session["id"]), prompt)
+    execution_plan = build_execution_plan(ROOT, prompt, dry_run=False)
+    if execution_plan.get("configuration_tasks"):
+        result = agentic_needs_input_from_plan(prompt, execution_plan)
+        return finalize_agent_session(result, session, prompt, backend=args.llm)
+    model_plan = execution_plan.get("model_plan") if isinstance(execution_plan.get("model_plan"), dict) else build_model_plan(prompt)
+    review_gate = execution_plan.get("review_gate") if isinstance(execution_plan.get("review_gate"), dict) else build_review_gate(prompt, model_plan=model_plan)
+    local_llm_execution = maybe_delegate_local_llm(prompt, model_plan)
+    coordinator_prompt = enrich_prompt_with_local_result(contextual_prompt, local_llm_execution)
     result = invoke_agent_prompt(
-        contextual_prompt,
+        coordinator_prompt,
         args.llm,
         public_name=name,
         allow_fallback=not args.no_llm_fallback,
     )
+    review_result = {
+        "kind": "execution-review",
+        "agent_id": "execution-reviewer",
+        "capability_id": "review-final-output",
+        "status": "not-run",
+        "ok": False,
+    }
+    if result.get("ok"):
+        result, review_gate, review_result = enforce_execution_review(
+            prompt=prompt,
+            result=result,
+            review_gate=review_gate,
+            execution_plan=execution_plan,
+            producer_backend=str(result.get("llm_backend") or args.llm or ""),
+        )
+        if review_result.get("ok"):
+            execution_plan = mark_review_task(execution_plan, reviewer=str(review_result.get("llm_backend") or "execution-reviewer"))
+        elif review_gate.get("status") == "needs-review":
+            execution_plan = mark_review_task_needs_review(execution_plan, review_result)
+    result["model_plan"] = model_plan
+    result["local_llm_execution"] = local_llm_execution
+    result["review_gate"] = review_gate
+    result["review_result"] = review_result
+    result["review_task"] = execution_plan.get("review_task")
+    result["execution_plan"] = execution_plan
+    result["orchestration_trace"] = execution_plan.get("trace", [])
     result["prompt_length"] = len(prompt)
     result["session_context_applied"] = contextual_prompt != prompt
+    result["local_context_applied"] = coordinator_prompt != contextual_prompt
     if result.get("response"):
         result["response"] = enforce_identity_response(str(result["response"]), prompt, name=name)
     result["identity"] = {"name": name, "source": "local"}
     return finalize_agent_session(result, session, prompt, backend=result.get("llm_backend") or args.llm)
 
 
+def mark_review_task_needs_review(execution_plan: dict[str, Any], review_result: dict[str, Any]) -> dict[str, Any]:
+    task = dict(execution_plan.get("review_task") or {})
+    if task:
+        task["status"] = "needs-review"
+        task["reviewer"] = None
+        task["message"] = review_result.get("message")
+        execution_plan["review_task"] = task
+    return execution_plan
+
+
+def agentic_needs_input_from_plan(prompt: str, execution_plan: dict[str, Any]) -> dict[str, Any]:
+    configuration_task = next(
+        (task for task in execution_plan.get("configuration_tasks") or [] if isinstance(task, dict)),
+        {},
+    )
+    wizard = configuration_task.get("setup_wizard") if isinstance(configuration_task.get("setup_wizard"), dict) else {}
+    provider = configuration_task.get("provider") or wizard.get("provider")
+    payload = {
+        "kind": "agent",
+        "status": "needs-input",
+        "ok": False,
+        "mode": "agentic-plan",
+        "prompt_received": True,
+        "prompt_length": len(prompt),
+        "provider": provider,
+        "source_provider": provider,
+        "requires_source": True,
+        "execution_plan": execution_plan,
+        "orchestration_trace": execution_plan.get("trace", []),
+        "setup_wizard": wizard,
+        "next_question": wizard.get("next_question"),
+        "message": wizard.get("message") or "O plano multiagente precisa de configuracao antes de executar.",
+        "next_steps": [
+            "Responda a pergunta do wizard para autorizar ou negar a configuracao deste provider.",
+            "Depois de configurar a fonte, reexecute ou retome o mesmo prompt.",
+        ],
+        "exit_code": 2,
+    }
+    return persist_setup_wizard_payload(payload, execution_plan=execution_plan)
+
+
+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
+
+
 def dispatch_natural_operational_prompt(prompt: str) -> dict[str, Any] | None:
     normalized = " ".join(prompt.lower().split())
+    control_result = dispatch_natural_control_prompt(normalized)
+    if control_result:
+        control_result["prompt_received"] = True
+        control_result["prompt_length"] = len(prompt)
+        return control_result
     if "agenda" in normalized:
         if "amanha" in normalized or "amanhã" in normalized:
             payload = calendar_tomorrow()
@@ -1028,9 +1413,21 @@ def dispatch_natural_operational_prompt(prompt: str) -> dict[str, Any] | None:
     return None
 
 
+def dispatch_natural_control_prompt(normalized_prompt: str) -> dict[str, Any] | None:
+    return route_natural_control_prompt(ROOT, normalized_prompt)
+
+
 def build_agent_dry_run_plan(prompt: str, args: argparse.Namespace) -> dict[str, Any]:
     normalized = " ".join(prompt.lower().split())
+    control_plan = plan_natural_control_prompt(ROOT, normalized)
+    if control_plan:
+        control_plan["prompt_received"] = True
+        control_plan["prompt_length"] = len(prompt)
+        return control_plan
     route = route_prompt(prompt)
+    execution_plan = build_execution_plan(ROOT, prompt, dry_run=True)
+    model_plan = execution_plan.get("model_plan") if isinstance(execution_plan.get("model_plan"), dict) else build_model_plan(prompt, route=route)
+    review_gate = execution_plan.get("review_gate") if isinstance(execution_plan.get("review_gate"), dict) else build_review_gate(prompt, route=route, model_plan=model_plan)
     plan: dict[str, Any] = {
         "kind": "agent",
         "status": "planned",
@@ -1047,6 +1444,10 @@ def build_agent_dry_run_plan(prompt: str, args: argparse.Namespace) -> dict[str,
         "providers": {"used": [], "missing": [], "skipped": []},
         "commands": [],
         "permissions": [],
+        "model_plan": model_plan,
+        "review_gate": review_gate,
+        "execution_plan": execution_plan,
+        "orchestration_trace": execution_plan.get("trace", []),
         "response": "Dry-run: nenhuma chamada LLM ou escrita externa foi executada.",
     }
     if "agenda" in normalized:
@@ -1120,7 +1521,8 @@ def finalize_agent_session(
     return result
 
 
-def invoke_deterministic_route(prompt: str, route: dict[str, Any]) -> dict[str, Any]:
+def invoke_agentic_route(prompt: str, route: dict[str, Any]) -> dict[str, Any]:
+    execution_plan = build_execution_plan(ROOT, prompt, dry_run=False)
     try:
         source = resolve_source(
             provider=route.get("provider"),
@@ -1131,43 +1533,96 @@ def invoke_deterministic_route(prompt: str, route: dict[str, Any]) -> dict[str,
         raise DevKitError(str(exc)) from exc
 
     if not source:
-        return {
+        wizard = missing_source_wizard(prompt, route, root=ROOT)
+        if execution_plan.get("configuration_tasks"):
+            execution_plan["configuration_tasks"][0]["setup_wizard"] = wizard
+        execution_plan["status"] = "needs-input"
+        execution_plan["trace"] = [
+            {"agent_id": "task-orchestrator", "action": "plan", "status": "needs-input"},
+            {"agent_id": "provider-configurator", "action": "configure", "status": "waiting-for-user"},
+        ]
+        payload = {
             "kind": "agent",
             "status": "needs-input",
             "ok": False,
             "requires_source": True,
+            "provider": route.get("provider"),
             "source_provider": route.get("provider"),
             "prompt_received": True,
             "prompt_length": len(prompt),
             "route": route,
             "napkin": napkin_context(ROOT, agent_id=route.get("agent_id")),
-            "message": "agent identified the task, but no reusable source is configured for this provider.",
+            "execution_plan": execution_plan,
+            "orchestration_trace": execution_plan.get("trace", []),
+            "setup_wizard": wizard,
+            "next_question": wizard.get("next_question"),
+            "message": wizard.get("message"),
             "next_steps": [
-                "Configure a source with `agent source add azure-sustentacao --provider azure-devops --config project=<project> --env AZURE_DEVOPS_PAT=AZURE_DEVOPS_PAT --default-for card`.",
-                "Use `--config fixture=<path>` for local fixture-based tests or demos.",
-                "Rerun the same prompt after configuring the source.",
+                "Responda a pergunta do wizard para autorizar ou negar a configuracao desta fonte.",
+                "Se preferir teste local, configure uma source com fixture sem armazenar segredos.",
+                "O prompt original sera retomado apos a fonte reutilizavel ser configurada.",
             ],
             "exit_code": 2,
         }
+        return persist_setup_wizard_payload(payload, execution_plan=execution_plan, route=route)
 
-    agent = load_agent(str(route["agent_id"]))
-    capability_args = [*route.get("args", []), "--source", str(source["id"])]
-    result = run_capability(agent, str(route["capability_id"]), capability_args, capture_output=True)
+    execution_plan = attach_source_to_primary_task(execution_plan)
+    executed, blocked = execute_plan_tasks(
+        execution_plan,
+        load_agent=load_agent,
+        run_capability=lambda agent, capability_id, capability_args: run_capability(agent, capability_id, capability_args, capture_output=True),
+    )
+    execution_plan = mark_plan_after_execution(execution_plan, executed, blocked)
+    result = (executed[0].get("result") if executed else blocked[0].get("result") if blocked and isinstance(blocked[0].get("result"), dict) else {}) or {}
     response = result.get("stdout") or result.get("error") or ""
     record_usage(prompt, route=route, source_id=str(source["id"]))
+    model_plan = execution_plan.get("model_plan") if isinstance(execution_plan.get("model_plan"), dict) else build_model_plan(prompt, route=route)
+    review_gate = execution_plan.get("review_gate") if isinstance(execution_plan.get("review_gate"), dict) else build_review_gate(prompt, route=route, model_plan=model_plan)
+    review_payload = {
+        "kind": "agent",
+        "status": execution_plan.get("status") if execution_plan.get("status") != "partial" else result.get("status"),
+        "ok": bool(executed) and not blocked,
+        "response": response,
+    }
+    review_result = {
+        "kind": "execution-review",
+        "agent_id": "execution-reviewer",
+        "capability_id": "review-final-output",
+        "status": "not-run",
+        "ok": False,
+    }
+    if result.get("ok"):
+        review_payload, review_gate, review_result = enforce_execution_review(
+            prompt=prompt,
+            result=review_payload,
+            review_gate=review_gate,
+            execution_plan=execution_plan,
+            producer_backend="deterministic-capability",
+        )
+        if review_result.get("ok"):
+            execution_plan = mark_review_task(execution_plan, reviewer=str(review_result.get("llm_backend") or "execution-reviewer"))
+        elif review_gate.get("status") == "needs-review":
+            execution_plan = mark_review_task_needs_review(execution_plan, review_result)
     return {
         "kind": "agent",
-        "status": result.get("status"),
-        "ok": result.get("ok", False),
-        "mode": "deterministic-route",
+        "status": review_payload.get("status"),
+        "ok": bool(review_payload.get("ok")),
+        "mode": "agentic-route",
+        "legacy_mode": "deterministic-route",
         "prompt_received": True,
         "prompt_length": len(prompt),
         "route": route,
         "source": public_source(source),
         "napkin": napkin_context(ROOT, agent_id=route.get("agent_id"), source_id=str(source["id"])),
-        "response": response,
+        "model_plan": model_plan,
+        "review_gate": review_gate,
+        "review_result": review_result,
+        "review_task": execution_plan.get("review_task"),
+        "execution_plan": execution_plan,
+        "orchestration_trace": execution_plan.get("trace", []),
+        "response": review_payload.get("response") or response,
         "result": result,
-        "exit_code": result.get("exit_code", 0 if result.get("ok") else 1),
+        "exit_code": review_payload.get("exit_code", result.get("exit_code", 0 if executed and not blocked else 1)),
     }
 
 
@@ -1361,9 +1816,9 @@ def run_capability(
             next_steps=guardrail["next_steps"],
             exit_code=2,
         )
-    readiness = evaluate_provider_requirements(ROOT, data)
+    readiness = evaluate_provider_requirements(ROOT, data, capability_args)
     if not readiness["ready"]:
-        return run_payload(
+        payload = run_payload(
             status=readiness["status"],
             agent=summarize_agent(agent),
             capability=data.get("id", capability_id),
@@ -1377,6 +1832,18 @@ def run_capability(
             artifacts=readiness["artifacts"],
             exit_code=readiness.get("exit_code"),
         )
+        wizard = setup_wizard_from_readiness(readiness, agent=summarize_agent(agent), capability_id=str(data.get("id", capability_id)))
+        if wizard:
+            payload["setup_wizard"] = wizard
+            payload["next_question"] = wizard.get("next_question")
+            payload["configuration_agent"] = wizard.get("owner_agent")
+            payload["next_steps"] = [
+                "Responda a pergunta do wizard para autorizar ou negar a configuracao deste provider.",
+                "Informe uma referencia segura de credencial por variavel de ambiente, arquivo ou cadeia nativa quando solicitado.",
+                "Reexecute ou retome a mesma capability depois que a configuracao estiver salva.",
+            ]
+            payload = persist_setup_wizard_payload(payload)
+        return payload
 
     runner_ref = (data.get("entrypoint", {}) or {}).get("runner")
     if not runner_ref:
@@ -1495,6 +1962,26 @@ def supports_runtime_source(agent_id: str, capability_id: str) -> bool:
     return agent_id == "azure-devops-orchestrator" and capability_id == "read-card"
 
 
+def setup_wizard_from_readiness(readiness: dict[str, Any], *, agent: dict[str, Any], capability_id: str) -> dict[str, Any] | None:
+    providers = readiness.get("providers") if isinstance(readiness.get("providers"), dict) else {}
+    missing = providers.get("missing") or []
+    if not missing:
+        return None
+    provider_id = str(missing[0])
+    details = providers.get("details") or []
+    detail = next((item for item in details if isinstance(item, dict) and item.get("id") == provider_id), {})
+    try:
+        return provider_wizard_from_requirement(
+            ROOT,
+            provider_id,
+            agent_id=str(agent.get("id") or ""),
+            capability_id=capability_id,
+            reason=str(detail.get("purpose") or "Provider is required but not configured."),
+        )
+    except Exception:
+        return None
+
+
 def doctor(project: str | None = None, home: str | None = None, scope: str = "auto") -> dict[str, Any]:
     agents = list_agents()
     capabilities = list_all_capabilities()
@@ -1704,6 +2191,8 @@ def print_human(result: dict[str, Any]) -> None:
         print_source_configure(result)
     elif kind == "source-remove":
         print_source_remove(result)
+    elif kind in {"wizards", "wizard"}:
+        print_wizard(result)
     elif kind == "memory":
         print_memory(result)
     elif kind == "memory-path":
@@ -1748,6 +2237,12 @@ def print_human(result: dict[str, Any]) -> None:
         print_permissions(result)
     elif kind in {"audit", "audit-entry", "audit-export"}:
         print_audit(result)
+    elif kind == "config":
+        print_config(result)
+    elif kind in {"tools", "tool", "integrations", "integration", "skills", "skill", "decisions", "decision", "decisions-reset"}:
+        print_control(result)
+    elif kind in {"ollama-status", "ollama-models", "ollama-pull", "ollama-update"}:
+        print_ollama(result)
     elif kind == "install":
         print_install(result)
     else:
@@ -1875,6 +2370,15 @@ def print_agent_response(result: dict[str, Any]) -> None:
         print(result.get("response", ""))
         return
     print(result.get("message") or result.get("response") or "Agent execution did not complete.")
+    question = result.get("next_question") or ((result.get("setup_wizard") or {}).get("next_question") if isinstance(result.get("setup_wizard"), dict) else None)
+    if isinstance(question, dict) and question.get("text"):
+        print(f"\nPergunta: {question['text']}")
+        if question.get("type") == "confirm":
+            print("[s/N]")
+    wizard = result.get("setup_wizard") if isinstance(result.get("setup_wizard"), dict) else {}
+    if wizard.get("wizard_id"):
+        print(f"\nWizard: {wizard['wizard_id']}")
+        print(f"Responder: agent wizard answer {wizard['wizard_id']} <resposta>")
     if result.get("llm_backend"):
         print(f"Requested backend: {result['llm_backend']}")
     if result.get("next_steps"):
@@ -1883,6 +2387,33 @@ def print_agent_response(result: dict[str, Any]) -> None:
             print(f"- {step}")
 
 
+def print_wizard(result: dict[str, Any]) -> None:
+    if result.get("kind") == "wizards":
+        items = result.get("items") or []
+        print(f"Wizards: {len(items)}")
+        for item in items:
+            print(f"- {item.get('wizard_id')}  {item.get('status')}  {item.get('provider')}")
+        return
+    wizard = result.get("wizard") if isinstance(result.get("wizard"), dict) else result.get("setup_wizard")
+    if not isinstance(wizard, dict):
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return
+    print(f"Wizard {wizard.get('wizard_id')}: {wizard.get('status')}")
+    print(f"Provider: {wizard.get('provider')}")
+    question = result.get("next_question") or wizard.get("next_question")
+    if isinstance(question, dict) and question.get("text"):
+        print(f"Pergunta: {question['text']}")
+        if question.get("type") == "confirm":
+            print("[s/N]")
+        print(f"Responder: agent wizard answer {wizard.get('wizard_id')} <resposta>")
+    if result.get("source_result"):
+        source = result["source_result"].get("source") or {}
+        print(f"Source configurada: {source.get('id')}")
+    if result.get("resumed_prompt"):
+        resume = result.get("resume_result") or {}
+        print(f"Prompt retomado: {resume.get('status')}")
+
+
 def print_sources(result: dict[str, Any]) -> None:
     print(f"Sources config: {result['config_path']}")
     if not result["items"]:
@@ -2268,6 +2799,58 @@ def print_credential_backends(result: dict[str, Any]) -> None:
         print(f"- {item}")
 
 
+def print_config(result: dict[str, Any]) -> None:
+    print(f"Config: {result.get('path')}")
+    if result.get("llm"):
+        print(f"Primary LLM: {(result['llm'] or {}).get('primary') or '-'}")
+    if result.get("ollama"):
+        print(f"Ollama: {(result['ollama'] or {}).get('status')}")
+
+
+def print_control(result: dict[str, Any]) -> None:
+    kind = result.get("kind")
+    if kind == "decisions-reset":
+        print(f"Decisions reset: {result.get('category') or 'all'}")
+        print(f"Path: {result.get('path')}")
+        return
+    if "items" in result:
+        print(f"{kind}:")
+        for item in result.get("items") or []:
+            print(f"- {item.get('category')}:{item.get('id')}  {item.get('state')}")
+        if not result.get("items"):
+            print("- none")
+        return
+    item = result.get("item") or result
+    print(f"{item.get('category') or result.get('category')}:{item.get('id') or result.get('id')}  {item.get('state') or result.get('state')}")
+
+
+def print_ollama(result: dict[str, Any]) -> None:
+    kind = result.get("kind")
+    if kind == "ollama-status":
+        print(f"Ollama: {result.get('status')}")
+        print(f"Binary: {result.get('binary') or '-'}")
+        print(f"Version: {result.get('version') or '-'}")
+        daemon = result.get("daemon") or {}
+        print(f"Daemon: {daemon.get('status') or '-'}")
+        print(f"Models: {result.get('model_count', 0)}")
+        if result.get("install_plan"):
+            print(f"Install: {(result['install_plan'] or {}).get('command')}")
+        return
+    if kind == "ollama-models":
+        print(f"Ollama models: {result.get('status')}")
+        for item in result.get("items") or []:
+            print(f"- {item.get('name')}  {item.get('size') or '-'}")
+        if not result.get("items"):
+            print("- none")
+        return
+    print(f"{kind}: {result.get('status')}")
+    if result.get("command"):
+        command = result["command"]
+        print("Command: " + (" ".join(command) if isinstance(command, list) else str(command)))
+    if result.get("message"):
+        print(result["message"])
+
+
 def print_install(result: dict[str, Any]) -> None:
     print(f"AI DevKit install: {result['status']}")
     print(f"Scope: {result['scope']}")