agent-devkit 0.1.5 → 0.1.6

package/runtime/cli/aikit/execution_reviewer.py

@@ -0,0 +1,174 @@
+"""Runtime execution for the execution-reviewer agent."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cli.aikit.llm import BACKENDS, candidate_backend_ids, doctor_backend, invoke_agent_prompt, load_config
+from cli.aikit.review_gate import mark_reviewed
+
+
+PREFERRED_REVIEW_BACKENDS = ("claude-code", "codex-cli")
+REVIEW_OK_MARKER = "REVIEW OK"
+REVIEW_BLOCKED_MARKER = "REVIEW BLOCKED"
+
+
+def enforce_execution_review(
+    *,
+    prompt: str,
+    result: dict[str, Any],
+    review_gate: dict[str, Any],
+    execution_plan: dict[str, Any] | None = None,
+    producer_backend: str | None = None,
+) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]]:
+    """Run a second concrete review when required and apply the gate outcome."""
+    if not review_gate.get("required"):
+        review_result = {
+            "kind": "execution-review",
+            "agent_id": "execution-reviewer",
+            "capability_id": "review-final-output",
+            "status": "not-required",
+            "ok": True,
+        }
+        return result, review_gate, review_result
+
+    response = str(result.get("response") or result.get("message") or "")
+    review_backend = select_review_backend(producer_backend=producer_backend, preferred=review_gate.get("preferred_reviewers") or [])
+    if not review_backend:
+        review_result = needs_review("No configured independent reviewer backend is available.", producer_backend=producer_backend)
+        return block_for_review(result, review_gate, review_result)
+
+    review_prompt = build_review_prompt(prompt=prompt, response=response, review_gate=review_gate, execution_plan=execution_plan)
+    invoked = invoke_agent_prompt(
+        review_prompt,
+        review_backend,
+        public_name="Execution Reviewer",
+        allow_fallback=False,
+    )
+    decision = parse_review_decision(str(invoked.get("response") or ""))
+    review_result = {
+        "kind": "execution-review",
+        "agent_id": "execution-reviewer",
+        "capability_id": "review-final-output",
+        "capability": "execution-reviewer.review-final-output",
+        "status": review_status(invoked=invoked, decision=decision),
+        "ok": bool(invoked.get("ok")) and decision == "approved",
+        "llm_backend": invoked.get("llm_backend"),
+        "producer_backend": producer_backend,
+        "decision": decision,
+        "response": invoked.get("response"),
+        "message": invoked.get("message"),
+        "attempts": invoked.get("llm_backend_attempts"),
+    }
+    if not invoked.get("ok"):
+        return block_for_review(result, review_gate, review_result)
+    if decision == "blocked":
+        review_result["message"] = "Execution reviewer blocked the proposed final output."
+        return block_for_review(result, review_gate, review_result)
+    if decision != "approved":
+        review_result["message"] = "Execution reviewer did not return REVIEW OK."
+        return block_for_review(result, review_gate, review_result)
+    reviewed_gate = mark_reviewed(review_gate, reviewer=str(invoked.get("llm_backend") or review_backend), notes=str(invoked.get("response") or "Reviewed."))
+    return result, reviewed_gate, review_result
+
+
+def select_review_backend(*, producer_backend: str | None, preferred: list[str]) -> str | None:
+    config = load_config()
+    candidates = candidate_backend_ids(config=config, allow_fallback=True)
+    preferred_order = [item for item in list(preferred or []) + list(PREFERRED_REVIEW_BACKENDS) if item in BACKENDS]
+    ordered = [item for item in preferred_order if item in candidates]
+    ordered.extend(item for item in candidates if item not in ordered and item != "ollama")
+    for backend_id in ordered:
+        if backend_id == producer_backend:
+            continue
+        backend = doctor_backend(BACKENDS[backend_id], config)
+        if backend.get("status") == "ok":
+            return backend_id
+    return None
+
+
+def build_review_prompt(
+    *,
+    prompt: str,
+    response: str,
+    review_gate: dict[str, Any],
+    execution_plan: dict[str, Any] | None,
+) -> str:
+    plan_summary = {}
+    if isinstance(execution_plan, dict):
+        plan_summary = {
+            "status": execution_plan.get("status"),
+            "coordinator": (execution_plan.get("coordinator_agent") or {}).get("id") if isinstance(execution_plan.get("coordinator_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 execution_plan.get("specialist_tasks") or []
+                if isinstance(task, dict)
+            ],
+        }
+    return "\n".join(
+        [
+            "Revise a entrega final do Agent DevKit antes da conclusao.",
+            "Verifique aderencia ao pedido, riscos, lacunas, evidencias, uso indevido de credenciais e necessidade de bloquear.",
+            "Responda com uma decisao objetiva: REVIEW OK ou REVIEW BLOCKED, seguida de justificativa curta.",
+            "",
+            f"Motivo do review gate: {review_gate.get('reason')}",
+            f"Prompt original: {prompt}",
+            f"Resumo do plano: {plan_summary}",
+            "",
+            "Resposta final proposta:",
+            response,
+        ]
+    )
+
+
+def parse_review_decision(response: str) -> str:
+    upper = response.upper()
+    if REVIEW_BLOCKED_MARKER in upper:
+        return "blocked"
+    if REVIEW_OK_MARKER in upper:
+        return "approved"
+    return "unstructured"
+
+
+def review_status(*, invoked: dict[str, Any], decision: str) -> str:
+    if not invoked.get("ok"):
+        return str(invoked.get("status", "failed"))
+    if decision == "blocked":
+        return "blocked"
+    if decision != "approved":
+        return "needs-review"
+    return "ok"
+
+
+def needs_review(message: str, *, producer_backend: str | None) -> dict[str, Any]:
+    return {
+        "kind": "execution-review",
+        "agent_id": "execution-reviewer",
+        "capability_id": "review-final-output",
+        "capability": "execution-reviewer.review-final-output",
+        "status": "needs-review",
+        "ok": False,
+        "producer_backend": producer_backend,
+        "message": message,
+    }
+
+
+def block_for_review(
+    result: dict[str, Any],
+    review_gate: dict[str, Any],
+    review_result: dict[str, Any],
+) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]]:
+    blocked = dict(result)
+    blocked["status"] = "needs-review"
+    blocked["ok"] = False
+    blocked["exit_code"] = 2
+    blocked["message"] = review_result.get("message") or "Execution requires review before completion."
+    gate = dict(review_gate)
+    gate["status"] = "needs-review"
+    gate["reviewer"] = None
+    gate["notes"] = review_result.get("message")
+    return blocked, gate, review_result

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

@@ -0,0 +1,112 @@
+"""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
+
+
+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 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",
+        "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 [])
+    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"Acoes proibidas: {forbidden}.",
+            "Retorne um 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",
+        "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(