agent-devkit 0.1.5 → 0.2.0

package/runtime/cli/aikit/architecture.py

@@ -0,0 +1,84 @@
+"""Public architecture contract for Agent DevKit."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from cli.aikit.acceptance import acceptance_model
+from cli.aikit.agent_registry import load_agent_registry
+from cli.aikit.impact_map import ownership_model
+from cli.aikit.roadmap import implementation_phases, problem_phase_map, recommended_initial_order
+from cli.aikit.runtime_paths import ROOT
+
+
+def architecture_contract(root: Path = ROOT) -> dict[str, Any]:
+    registry = load_agent_registry(root)
+    agents = registry.get("agents") or {}
+    capabilities = registry.get("capabilities") or {}
+    runtime_agents = sorted(
+        agent_id
+        for agent_id, agent in agents.items()
+        if isinstance(agent, dict) and str(agent.get("kind") or "") == "runtime-agent"
+    )
+    specialist_agents = sorted(agent_id for agent_id in agents if agent_id not in set(runtime_agents))
+    executable_capabilities = sum(
+        1
+        for capability in capabilities.values()
+        if isinstance(capability, dict) and capability.get("has_runner")
+    )
+    return {
+        "kind": "architecture",
+        "schema_version": "ai-devkit.architecture/v1",
+        "principal_agent": {
+            "id": "agent-devkit",
+            "name": "Agent DevKit",
+            "role": "runtime-agent",
+            "description": "Agente principal que coordena modulos especialistas, capabilities, automacoes, providers, memoria, guardrails e backends LLM.",
+        },
+        "model": {
+            "agent_devkit": "agente principal",
+            "agents": "modulos especialistas internos versionados em agents/*",
+            "capabilities": "unidades executaveis do sistema",
+            "runners": "automacoes deterministicas para tarefas conhecidas",
+            "providers": "integracoes externas acessadas por contratos controlados",
+            "llms": "cerebros plugaveis para conversa, decisao e revisao quando necessario",
+            "hosts": "interfaces ou consumidores externos, como CLI, MCP, Codex, Claude, OpenClaw e OpenCode",
+        },
+        "core_responsibilities": [
+            "planner_router",
+            "memory_sessions",
+            "permissions_guardrails",
+            "audit",
+            "provider_registry",
+            "llm_backend_selection",
+            "capability_execution",
+            "review_gate",
+        ],
+        "decision_targets": [
+            "deterministic_capability",
+            "local_mini_brain",
+            "external_professional_llm",
+            "human_input",
+            "external_provider",
+            "external_host_via_mcp",
+        ],
+        "interfaces": [
+            "cli",
+            "mcp",
+            "host_adapter",
+        ],
+        "implementation_phases": implementation_phases(),
+        "recommended_initial_order": recommended_initial_order(),
+        "problem_phase_map": problem_phase_map(),
+        "acceptance_model": acceptance_model(),
+        "impact_model": ownership_model(),
+        "counts": {
+            "runtime_agents": len(runtime_agents),
+            "specialist_agents": len(specialist_agents),
+            "capabilities": len(capabilities),
+            "executable_capabilities": executable_capabilities,
+        },
+        "runtime_agents": runtime_agents,
+        "status": "partially-implemented",
+    }

package/runtime/cli/aikit/audit.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import errno
 import getpass
 import json
 import re
@@ -11,12 +12,18 @@ from pathlib import Path
 from typing import Any
 
 from cli.aikit.app_home import audit_home, ensure_app_home
+from cli.aikit.autonomy import summarize_autonomy_contract
 from cli.aikit.memory import normalize_prompt, redact_secrets
+from cli.aikit.mini_brain import summarize_mini_brain
 
 
 AUDIT_VERSION = 1
 
 
+class AuditRedactionError(RuntimeError):
+    """Raised when an audit payload cannot be safely redacted."""
+
+
 def now_utc() -> datetime:
     return datetime.now(timezone.utc)
 
@@ -45,21 +52,30 @@ def record_audit(
     args: dict[str, Any],
     result: dict[str, Any] | None = None,
     error: str | None = None,
+    origin: str = "unknown",
 ) -> dict[str, Any]:
     created_at = now_iso()
     execution_id = f"exec_{now_utc().strftime('%Y%m%d%H%M%S')}_{uuid.uuid4().hex[:8]}"
     prompt = extract_prompt(args)
-    safe_result = redact_value(result or {})
+    try:
+        safe_result = redact_value(result or {})
+        safe_prompt = redact_secrets(prompt) if prompt else None
+        safe_error = redact_secrets(error) if error else None
+    except Exception as exc:  # noqa: BLE001 - never write an unredacted audit fallback.
+        raise AuditRedactionError("audit redaction failed") from exc
     entry = {
         "version": AUDIT_VERSION,
         "id": execution_id,
         "created_at": created_at,
+        "origin": normalize_origin(origin),
         "user": safe_user(),
         "command": command,
-        "prompt": redact_secrets(prompt) if prompt else None,
+        "prompt": safe_prompt,
         "prompt_normalized": normalize_prompt(prompt) if prompt else None,
         "session": extract_session(safe_result),
         "route": safe_result.get("route"),
+        "orchestration": extract_orchestration(safe_result),
+        "autonomy": summarize_autonomy_contract(safe_result.get("autonomy_contract")),
         "agent": extract_agent(safe_result, args),
         "providers": extract_providers(safe_result),
         "sources": extract_sources(safe_result),
@@ -69,7 +85,7 @@ def record_audit(
         "token_estimate": extract_token_estimate(safe_result),
         "external_actions": extract_external_actions(safe_result),
         "result": summarize_result(safe_result),
-        "error": redact_secrets(error) if error else None,
+        "error": safe_error,
         "redaction_applied": True,
     }
     day_home = audit_day_home(created_at[:10])
@@ -80,6 +96,64 @@ def record_audit(
     return {"id": execution_id, "json_path": str(json_path), "markdown_path": str(md_path)}
 
 
+def try_record_audit(
+    *,
+    command: str | None,
+    args: dict[str, Any],
+    result: dict[str, Any] | None = None,
+    error: str | None = None,
+    origin: str = "unknown",
+    required: bool = False,
+    recorder: Any | None = None,
+) -> dict[str, Any]:
+    """Record an audit trail and return a safe success or warning envelope."""
+
+    audit_recorder = recorder or record_audit
+    try:
+        audit = audit_recorder(command=command, args=args, result=result, error=error, origin=origin)
+    except TypeError as exc:
+        if recorder is None:
+            return {"audit_warning": audit_warning(exc, required=required)}
+        try:
+            audit = audit_recorder(command=command, args=args, result=result, error=error)
+        except Exception as fallback_exc:  # noqa: BLE001 - audit remains best-effort.
+            return {"audit_warning": audit_warning(fallback_exc, required=required)}
+    except Exception as exc:  # noqa: BLE001 - audit remains best-effort.
+        return {"audit_warning": audit_warning(exc, required=required)}
+    return {"audit": audit}
+
+
+def audit_warning(exc: Exception, *, required: bool = False) -> dict[str, Any]:
+    return {
+        "kind": "audit-warning",
+        "code": "audit_record_failed",
+        "status": "not-recorded",
+        "reason": classify_audit_error(exc),
+        "message": "Audit trail could not be written.",
+        "required": bool(required),
+    }
+
+
+def classify_audit_error(exc: Exception) -> str:
+    if isinstance(exc, AuditRedactionError):
+        return "redaction-error"
+    if isinstance(exc, PermissionError):
+        return "permission-denied"
+    if isinstance(exc, FileNotFoundError):
+        return "path-not-found"
+    if isinstance(exc, OSError) and getattr(exc, "errno", None) == errno.ENOSPC:
+        return "disk-full"
+    if isinstance(exc, (TypeError, ValueError)):
+        return "serialization-error"
+    return "unknown-audit-error"
+
+
+def normalize_origin(origin: str | None) -> str:
+    allowed = {"cli", "mcp", "scheduler", "wizard", "agent-prompt", "plugin", "core", "unknown"}
+    value = str(origin or "unknown").strip()
+    return value if value in allowed else "unknown"
+
+
 def list_audits(limit: int = 20) -> dict[str, Any]:
     items: list[dict[str, Any]] = []
     for path in sorted(ensure_audit_home().glob("*/*.json"), reverse=True):
@@ -231,6 +305,17 @@ def extract_sources(result: dict[str, Any]) -> list[Any]:
     source = result.get("source")
     if source:
         return [source]
+    if result.get("kind") == "source-configure" and result.get("status") == "blocked":
+        return [
+            {
+                "id": result.get("source_id"),
+                "provider": result.get("provider"),
+                "status": result.get("status"),
+                "field": result.get("field"),
+                "reason": result.get("reason"),
+                "stored_secret": False,
+            }
+        ]
     return []
 
 
@@ -282,6 +367,127 @@ def extract_external_actions(result: dict[str, Any]) -> list[dict[str, Any]]:
     return actions
 
 
+def extract_orchestration(result: dict[str, Any]) -> dict[str, Any] | None:
+    plan = result.get("execution_plan")
+    if not isinstance(plan, dict):
+        return None
+    return {
+        "kind": plan.get("kind"),
+        "status": plan.get("status"),
+        "coordinator_agent": (plan.get("coordinator_agent") or {}).get("id") if isinstance(plan.get("coordinator_agent"), dict) else None,
+        "domain_agent": (plan.get("domain_agent") or {}).get("id") if isinstance(plan.get("domain_agent"), dict) else None,
+        "specialist_tasks": [
+            {
+                "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")),
+        "trace": result.get("orchestration_trace") or plan.get("trace") or [],
+    }
+
+
+def summarize_collaboration_graph(value: Any) -> dict[str, Any] | None:
+    if not isinstance(value, dict):
+        return None
+    nodes = value.get("nodes") if isinstance(value.get("nodes"), list) else []
+    edges = value.get("edges") if isinstance(value.get("edges"), list) else []
+    return {
+        "schema_version": value.get("schema_version"),
+        "nodes": len(nodes),
+        "edges": len(edges),
+        "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 summarize_result(result: dict[str, Any]) -> dict[str, Any]:
     return {
         "kind": result.get("kind"),
@@ -305,6 +511,7 @@ def render_audit_md(entry: dict[str, Any]) -> str:
         f"# Audit {entry.get('id')}",
         "",
         f"- Created at: `{entry.get('created_at')}`",
+        f"- Origin: `{entry.get('origin') or 'unknown'}`",
         f"- User: `{entry.get('user')}`",
         f"- Command: `{entry.get('command')}`",
         f"- Status: `{(entry.get('result') or {}).get('status')}`",
@@ -326,6 +533,12 @@ def render_audit_md(entry: dict[str, Any]) -> str:
         json.dumps(entry.get("providers") or {}, ensure_ascii=False, indent=2, sort_keys=True),
         "```",
         "",
+        "## Orchestration",
+        "",
+        "```json",
+        json.dumps(entry.get("orchestration") or {}, ensure_ascii=False, indent=2, sort_keys=True),
+        "```",
+        "",
         "## Permissions",
         "",
         "```json",

package/runtime/cli/aikit/autonomy.py

@@ -0,0 +1,237 @@
+"""Controlled autonomy contracts for Agent DevKit plans and tasks."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+AUTONOMY_SCHEMA_VERSION = "ai-devkit.autonomy/v1"
+
+
+LEVELS = {
+    0: ("manual", "User runs commands or capabilities directly."),
+    1: ("assisted", "Agent DevKit suggests, asks, or delegates reasoning before execution."),
+    2: ("deterministic", "Known read-only or dry-run capabilities can execute without external LLM."),
+    3: ("supervised", "Side-effecting work requires explicit human confirmation."),
+    4: ("scheduled", "Recurring local tasks execute with limits, audit, and notifications."),
+    5: ("collaborative", "Multiple specialist agents are coordinated by the runtime."),
+    6: ("controlled-autonomy", "Composed workflows execute inside policy, budget, audit, and stop conditions."),
+}
+
+
+def build_autonomy_contract(
+    *,
+    model_plan: dict[str, Any],
+    routing_decision: dict[str, Any],
+    specialist_tasks: list[dict[str, Any]],
+    configuration_tasks: list[dict[str, Any]],
+    review_gate: dict[str, Any],
+    execution_model: dict[str, Any],
+    policy_summary: dict[str, Any],
+    collaboration_enabled: bool,
+    controller_enabled: bool,
+    scheduled: bool = False,
+) -> dict[str, Any]:
+    reasons: list[str] = []
+    blockers: list[str] = []
+    requires_human = False
+    model_strategy = str(model_plan.get("strategy") or "")
+    routing_status = str(routing_decision.get("status") or "")
+    has_specialists = bool(specialist_tasks)
+    has_multiple_specialists = len(specialist_tasks) > 1
+    supervised_side_effect_count = sum(1 for task in specialist_tasks if task_requires_supervision(task))
+
+    if routing_status in {"ambiguous", "low-confidence"}:
+        requires_human = True
+        blockers.append("routing-confirmation-required")
+        reasons.append("Routing requires human confirmation.")
+    if configuration_tasks:
+        requires_human = True
+        blockers.append("provider-configuration-required")
+        reasons.append("Provider/source configuration is required.")
+    if model_strategy == "human":
+        requires_human = True
+        blockers.append("human-model-strategy")
+        reasons.append("Model strategy selected human input.")
+    if supervised_side_effect_count:
+        requires_human = True
+        blockers.append("write-policy-confirmation-required")
+        reasons.append("One or more tasks require explicit confirmation by write policy.")
+
+    if scheduled:
+        level = 4
+        reasons.append("Execution is scheduled.")
+    elif requires_human and supervised_side_effect_count:
+        level = 3
+    elif requires_human:
+        level = 1
+    elif controller_enabled and collaboration_enabled and has_multiple_specialists:
+        level = 6
+        reasons.append("Controller can execute a composed specialist workflow within declared limits.")
+    elif collaboration_enabled and has_multiple_specialists:
+        level = 5
+        reasons.append("Plan coordinates multiple specialist agents.")
+    elif model_strategy == "automation" and has_specialists:
+        level = 2
+        reasons.append("Plan maps to deterministic autonomous-safe capability execution.")
+    elif has_specialists:
+        level = 2 if int(policy_summary.get("autonomous_safe") or 0) > 0 else 1
+        reasons.append("Plan selected known capability contracts.")
+    else:
+        level = 1
+        reasons.append("Plan needs reasoning, user input, or a configured LLM before autonomous execution.")
+
+    level_id, level_description = LEVELS[level]
+    limits = execution_model.get("limits") if isinstance(execution_model.get("limits"), dict) else {}
+    allowed_side_effects = (
+        execution_model.get("allowed_side_effects")
+        if isinstance(execution_model.get("allowed_side_effects"), dict)
+        else {}
+    )
+    execution_allowed = not blockers and level in {2, 4, 5, 6}
+    if model_strategy == "external-llm" and int(limits.get("max_llm_calls") or 0) > 0:
+        execution_allowed = True
+    if any(task_is_blocked_by_default(task) for task in specialist_tasks):
+        execution_allowed = False
+
+    status = "allowed" if execution_allowed else "needs-input" if requires_human else "planned"
+    if any(task_is_blocked_by_default(task) for task in specialist_tasks):
+        status = "blocked"
+
+    return {
+        "kind": "autonomy-contract",
+        "schema_version": AUTONOMY_SCHEMA_VERSION,
+        "level": level,
+        "level_id": level_id,
+        "level_description": level_description,
+        "status": status,
+        "execution_allowed": execution_allowed,
+        "requires_human": requires_human,
+        "requires_review": bool(review_gate.get("required")),
+        "can_call_capabilities": bool(allowed_side_effects.get("can_call_capabilities")),
+        "can_call_llm": allowed_side_effects.get("can_call_llm"),
+        "can_schedule": level in {2, 4, 5, 6} and not requires_human,
+        "audit_required": True,
+        "model_strategy": model_strategy or None,
+        "model_risk": model_plan.get("risk"),
+        "routing_status": routing_status or None,
+        "controller_enabled": bool(controller_enabled),
+        "collaboration_enabled": bool(collaboration_enabled),
+        "limits": limits,
+        "policy_summary": policy_summary,
+        "allowed_actions": allowed_actions_for_level(level, execution_allowed),
+        "blocked_actions": blocked_actions_for(level, blockers, model_plan),
+        "blockers": blockers,
+        "reasons": reasons,
+        "fallback": model_plan.get("fallback"),
+    }
+
+
+def build_task_autonomy_contract(
+    task: dict[str, Any],
+    *,
+    origin: str,
+    dry_run: bool = False,
+    permission: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    action = task.get("action") if isinstance(task.get("action"), dict) else {}
+    schedule = task.get("schedule") if isinstance(task.get("schedule"), dict) else {}
+    notify = task.get("notify") if isinstance(task.get("notify"), dict) else {}
+    permission = permission if isinstance(permission, dict) else {}
+    scheduled = origin == "scheduler" or schedule.get("type") not in {None, "manual"}
+    external_writes = action.get("external_writes") is True
+    permission_ok = permission.get("ok") is not False
+    requires_human = external_writes and not permission_ok
+    level = 4 if scheduled else 0
+    if requires_human:
+        level = 3
+    level_id, level_description = LEVELS[level]
+    execution_allowed = dry_run or not requires_human
+    status = "allowed" if execution_allowed else "needs-input"
+    blockers = ["external-write-permission-required"] if requires_human else []
+    return {
+        "kind": "autonomy-contract",
+        "schema_version": AUTONOMY_SCHEMA_VERSION,
+        "level": level,
+        "level_id": level_id,
+        "level_description": level_description,
+        "status": status,
+        "execution_allowed": execution_allowed,
+        "requires_human": requires_human,
+        "requires_review": external_writes,
+        "can_call_capabilities": action.get("type") == "capability",
+        "can_call_llm": action.get("type") == "prompt",
+        "can_schedule": scheduled,
+        "audit_required": origin == "scheduler",
+        "scheduled": scheduled,
+        "notification_required": bool(task.get("notifications") or notify),
+        "allowed_actions": allowed_actions_for_level(level, execution_allowed),
+        "blocked_actions": blocked_actions_for(level, blockers, {}),
+        "blockers": blockers,
+        "reasons": task_autonomy_reasons(scheduled=scheduled, external_writes=external_writes, dry_run=dry_run),
+    }
+
+
+def task_requires_supervision(task: dict[str, Any]) -> bool:
+    metadata = task.get("write_policy_metadata") if isinstance(task.get("write_policy_metadata"), dict) else {}
+    return bool(metadata.get("requires_confirmation") or metadata.get("blocked_by_default"))
+
+
+def task_is_blocked_by_default(task: dict[str, Any]) -> bool:
+    metadata = task.get("write_policy_metadata") if isinstance(task.get("write_policy_metadata"), dict) else {}
+    return bool(metadata.get("blocked_by_default"))
+
+
+def allowed_actions_for_level(level: int, execution_allowed: bool) -> list[str]:
+    if not execution_allowed:
+        return ["dry-run", "ask-human"]
+    actions = ["audit", "notify"]
+    if level >= 2:
+        actions.append("run-autonomous-safe-capability")
+    if level >= 4:
+        actions.append("run-scheduled-task")
+    if level >= 5:
+        actions.append("coordinate-specialists")
+    if level >= 6:
+        actions.append("run-controlled-workflow")
+    return actions
+
+
+def blocked_actions_for(level: int, blockers: list[str], model_plan: dict[str, Any]) -> list[str]:
+    blocked = set(model_plan.get("forbidden_actions") or [])
+    if blockers:
+        blocked.update({"execute-without-human-input", "external-write"})
+    if level < 4:
+        blocked.add("unbounded-loop")
+    blocked.add("destructive-action-without-confirmation")
+    return sorted(blocked)
+
+
+def task_autonomy_reasons(*, scheduled: bool, external_writes: bool, dry_run: bool) -> list[str]:
+    reasons = []
+    if scheduled:
+        reasons.append("Task is managed by the local scheduler contract.")
+    else:
+        reasons.append("Task is a manual local task run.")
+    if external_writes:
+        reasons.append("Task declares external write effects.")
+    if dry_run:
+        reasons.append("Dry-run permits planning without external effects.")
+    return reasons
+
+
+def summarize_autonomy_contract(value: Any) -> dict[str, Any] | None:
+    if not isinstance(value, dict):
+        return None
+    return {
+        "schema_version": value.get("schema_version"),
+        "level": value.get("level"),
+        "level_id": value.get("level_id"),
+        "status": value.get("status"),
+        "execution_allowed": value.get("execution_allowed") is True,
+        "requires_human": value.get("requires_human") is True,
+        "requires_review": value.get("requires_review") is True,
+        "model_strategy": value.get("model_strategy"),
+        "model_risk": value.get("model_risk"),
+        "blockers": list(value.get("blockers") or []),
+    }